home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / documents / RFC / rfc1203.txt < prev    next >
Text File  |  1994-08-01  |  121KB  |  2,747 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7. Network Working Group                                           J. Rice
  8. Request for Comments: 1203                                     Stanford
  9. Obsoletes: RFC 1064                                       February 1991
  10.  
  11.  
  12.               INTERACTIVE MAIL ACCESS PROTOCOL - VERSION 3
  13.  
  14. Status of this Memo
  15.  
  16.    This RFC suggests a method for workstations to access mail
  17.    dynamically from a mailbox server ("repository").  This RFC specifies
  18.    a standard for the SUMEX-AIM community and an Experimental Protocol
  19.    for the Internet community.  Discussion and suggestions for
  20.    improvement are requested.  Please refer to the current edition of
  21.    the "IAB Official Protocol Standards" for the standardization state
  22.    and status of this protocol.  Distribution of this memo is unlimited.
  23.  
  24. Scope
  25.  
  26.    The following document is a modified version of RFC 1064, the
  27.    definition of the IMAP2 protocol.  This RFC has been written
  28.    specifically as a counter proposal to RFC 1176, which itself proposes
  29.    modifications to IMAP2.  Sadly, RFC 1176 was made without internal
  30.    consultation with the IMAP community, so we are in a position of
  31.    feeling we have to present a counter proposal to what, if we do not
  32.    act, will become a de facto standard.  The reasons for this counter
  33.    proposal are numerous but fall mostly into the following categories:
  34.  
  35.       - IMAP2 is insufficiently powerful for a number of server/client
  36.         interactions which we believe to be important.  RFC 1176
  37.         negligibly enhances the functionality of IMAP2.
  38.  
  39.       - IMAP2 makes what we believe to be an erroneous definition for
  40.         unsolicited vs. solicited data.  IMAP3 as specified herein
  41.         attempts to correct this.  RFC 1176 makes no effort to remedy
  42.         these problems.
  43.  
  44.       - RFC 1176 has explicitly modified the intent of RFC 1064 by
  45.         allowing the server to make assumptions about the client's
  46.         caching architecture.  We believe this to be a grave error
  47.         and do not support it in this proposal.
  48.  
  49.       - RFC 1176 specifies a number of "optional" features in the
  50.         protocol without specifying a suitable metaprotocol by which
  51.         servers and clients can adequately negotiate over the set of
  52.         implemented features.  This proposal specifies a mechanism
  53.         by which servers and clients can come to an unambiguous
  54.         understanding about which features are usable by each party.
  55.  
  56.  
  57.  
  58. Rice                                                            [Page 1]
  59.  
  60. RFC 1203                         IMAP3                     February 1991
  61.  
  62.  
  63.  
  64.       - RFC 1176 pays only lip-service to being network protocol
  65.         independent and, in fact assumes the use of TCP/IP.  Neither
  66.         RFC 1064 nor this proposal make any such assumption.
  67.  
  68.    Although there are numerous other detailed objections to RFC 1176, we
  69.    believe that the above will serve to show that we believe strongly in
  70.    the importance of mailbox abstraction level mail protocols and, after
  71.    a couple of years of use of IMAP2 under RFC 1064 we believe that we
  72.    have a good enough understanding of the issues involved to be able to
  73.    take the next step.
  74.  
  75.    It is important to take this next step because of the rapid pace of
  76.    both mail system and user interface development.  We believe that,
  77.    for IMAP not to die in its infancy, IMAP must be ready to respond to
  78.    emerging ISO and RFC standards in mail, such as for multi-media mail.
  79.    We believe that RFC 1176 not only provides a very small increment in
  80.    functionality over RFC 1064 but also adds a number of bugs, which
  81.    would be detrimental to the IMAP cause.  Thus we propose the
  82.    following definition for IMAP3.
  83.  
  84. Compatibility notes:
  85.  
  86.    In revising the IMAP2 protocol it has been our intent, wherever
  87.    possible to make upwards compatible changes to produce IMAP3.  There
  88.    were, however, some places that had to be changed incompatibly in
  89.    order to compensate for either ambiguities in the IMAP2 protocol as
  90.    defined by RFC 1064 or behavior that proved undesirable in the light
  91.    of experience.
  92.  
  93.    It is our goal, however, that existing IMAP2 clients should still be
  94.    supported and that, at least for the foreseeable future, all IMAP3
  95.    servers will support IMAP2 behavior as their default mode.
  96.  
  97.    The following are the major differences between this proposal, RFC
  98.    1176 and RFC 1064:
  99.  
  100.       - In this proposal we specify a difference between "solicited" and
  101.         "unsolicited" data sent from the server.  It is generally the
  102.         case that data sent by the server can be sent either in response
  103.         to an explicit request by the client or by the server of its own
  104.         volition.  Any data that the server is required to sent to the
  105.         client as the result of a request is said to be solicited and
  106.         carries the same tag as the request that provoked it.  Any data
  107.         sent by the server to the client that is not required by the
  108.         protocol is said to be unsolicited and carries the special "*"
  109.         tag.  RFC 1176 preserves the original RFC 1064 terminology that
  110.         calls all such data sent by the server "unsolicited" even when
  111.  
  112.  
  113.  
  114. Rice                                                            [Page 2]
  115.  
  116. RFC 1203                         IMAP3                     February 1991
  117.  
  118.  
  119.         it is, in fact, solicited.
  120.  
  121.       - This proposal introduces the experimental concept of
  122.         distinguishing between Generic, Canonical and Concrete keys,
  123.         allowing the mailbox to be viewed as a relational database
  124.         indexed by these keys.  This should allow the IMAP protocol
  125.         to evolve away from its current reliance on RFC 822.  RFC 1176
  126.         does not have such a unifying model.
  127.  
  128.       - The SEARCH command has been changed so as to allow multiple
  129.         simultaneous searches to be made and to allow unsolicited
  130.         search messages to be sent by the server.  Such a change is
  131.         essential to allow more sophisticated servers that can process
  132.         commands asynchronously, possibly substantially delaying
  133.         searches over slow backing storage media, for example.  It is
  134.         also important to allow servers to be able to send unsolicited
  135.         search messages that might inform the client of interesting
  136.         patterns of messages, such as new and unseen mail.
  137.  
  138.       - This proposal introduces a specific protocol for the negotiation
  139.         of protocol versions and server features.  This is important
  140.         because it allows client/server pairs to come to an agreement on
  141.         what behavior is really available to it.  RFC 1176 introduces a
  142.         number of "optional" commands, which are in some way analogous
  143.         to "feature-introduced" commands in this proposal.  The principle
  144.         distinction between these is that in RFC 1176 there is no way
  145.         for a client to discover the set of optional commands, nor is
  146.         there a way for it to determine whether a specific command
  147.         really is supported, since RFC 1176 requires the use of the
  148.         "BAD" response if a feature is not supported.  There is,
  149.         therefore, no way for the client to determine why the attempted
  150.         command did not work.  This also means that, for example, a
  151.         client cannot disable certain user commands or make them
  152.         invisible on menus if they are not supported, since there
  153.         is no way for the client to discover whether the commands are
  154.         indeed supported without trying to execute such a command.
  155.  
  156.       - This proposal introduces a mechanism for clients to create and
  157.         delete user flags (keywords).  This is nor supported in either
  158.         RFC 1176 or RFC 1064, requiring the user to add keys manually
  159.         on the server, generally by editing some form of "init" file.
  160.  
  161.       - RFC 1064 has no mechanism for determining whether a mailbox is
  162.         readonly or not.  RFC 1176 introduces a non-enforced convention
  163.         of encoding data about the readonly status of a mailbox in the
  164.         SELECT message's OK respose comment field.  This is not regular
  165.         with respect to the rest of the protocol, in which the comment
  166.         field is used for no purpose other than documentation.  This
  167.  
  168.  
  169.  
  170. Rice                                                            [Page 3]
  171.  
  172. RFC 1203                         IMAP3                     February 1991
  173.  
  174.  
  175.         proposal introduces specific protocol additions for the dynamic
  176.         determination and modification of the readonly/readwrite status
  177.         of mailboxes.
  178.  
  179. Introduction
  180.  
  181.    The intent of the Interactive Mail Access Protocol, Version 3 (IMAP3)
  182.    is to allow a (possibly unreliable) workstation or similar machine to
  183.    access electronic mail from a reliable mailbox server in an efficient
  184.    manner.
  185.  
  186.    Although different in many ways from POP2 (RFC 937), IMAP3 may be
  187.    thought of as a functional superset of POP2, and the POP2 RFC was
  188.    used as a model for this RFC.  There was a cognizant reason for this;
  189.    RFC 937 deals with an identical problem and it was desirable to offer
  190.    a basis for comparison.
  191.  
  192.    Like POP2, IMAP3 specifies a means of accessing stored mail and not
  193.    of posting mail; this function is handled by a mail transfer protocol
  194.    such as SMTP (RFC 821).  A comparison with the DMSP protocol of
  195.    PCMAIL can be found at the end of "System Model and Philosophy"
  196.    section.
  197.  
  198.    This protocol assumes a reliable data stream such as provided by TCP
  199.    or any similar protocol.  When TCP is used, the IMAP server listens
  200.    on port 220.  When CHAOS is used the IMAP server listens for the
  201.    logical contact name "IMAP3".
  202.  
  203.    Communication in IMAP is defined to be using the ASCII character
  204.    interpretation of data.  Communication using other conventions may be
  205.    possible by the selection of features on some servers.
  206.  
  207. System Model and Philosophy
  208.  
  209.    Electronic mail is a primary means of communication for the widely
  210.    spread SUMEX-AIM community.  The advent of distributed workstations
  211.    is forcing a significant rethinking of the mechanisms employed to
  212.    manage such mail.  With mainframes, each user tends to receive and
  213.    process mail at the computer he used most of the time, his "primary
  214.    host".  The first inclination of many users when an independent
  215.    workstation is placed in front of them is to begin receiving mail at
  216.    the workstation, and, in fact, many vendors have implemented
  217.    facilities to do this.  However, this approach has several
  218.    disadvantages:
  219.  
  220.       (1)  Workstations (especially Lisp workstations) have a software
  221.            design that gives full control of all aspects of the system
  222.            to the user at the console.  As a result, background tasks,
  223.  
  224.  
  225.  
  226. Rice                                                            [Page 4]
  227.  
  228. RFC 1203                         IMAP3                     February 1991
  229.  
  230.  
  231.            like receiving mail, could well be kept from running for
  232.            long periods of time either because the user is asking to
  233.            use all of the machine's resources, or because, in the course
  234.            of working, the user has (perhaps accidentally) manipulated
  235.            the environment in such a way as to prevent mail reception.
  236.            This could lead to repeated failed delivery attempts by
  237.            outside agents.
  238.  
  239.       (2)  The hardware failure of a single workstation could keep its
  240.            user "off the air" for a considerable time, since repair of
  241.            individual workstation units might be delayed.  Given the
  242.            growing number of workstations spread throughout office
  243.            environments, quick repair would not be assured, whereas a
  244.            centralized mainframe is generally repaired very soon after
  245.            failure.
  246.  
  247.       (3)  It is more difficult to keep track of mailing addresses when
  248.            each person is associated with a distinct machine.  Consider
  249.            the difficulty in keeping track of a large number of postal
  250.            addresses or phone numbers, particularly if there was no
  251.            single address or phone number for an organization through
  252.            which you could reach any person in that organization.
  253.            Traditionally, electronic mail on the ARPANET involved
  254.            remembering a name and one of several "hosts" (machines)
  255.            whose name reflected the organization in which the
  256.            individual worked.  This was suitable at a time when most
  257.            organizations had only one central host.  It is less
  258.            satisfactory today unless the concept of a host is changed
  259.            to refer to an organizational entity and not a particular
  260.            machine.
  261.  
  262.       (4)  It is very difficult to keep a multitude of heterogeneous
  263.            workstations working properly with complex mailing protocols,
  264.            making it difficult to move forward as progress is made in
  265.            electronic communication and as new standards emerge.  Each
  266.            system has to worry about receiving incoming mail, routing
  267.            and delivering outgoing mail, formatting, storing, and
  268.            providing for the stability of mailboxes over a variety of
  269.            possible filing and mailing protocols.
  270.  
  271.    Consequently, while the workstation may be viewed as an Internet host
  272.    in the sense that it implements IP, it should not be viewed as the
  273.    entity which contains the user's mailbox.  Rather, a mail server
  274.    machine (sometimes called a "repository") should hold the mailbox,
  275.    and the workstation (hereafter referred to as a "client") should
  276.    access the mailbox via mail transactions.  Because the mail server
  277.    machine would be isolated from direct user manipulation, it could
  278.    achieve high software reliability easily, and, as a shared resource,
  279.  
  280.  
  281.  
  282. Rice                                                            [Page 5]
  283.  
  284. RFC 1203                         IMAP3                     February 1991
  285.  
  286.  
  287.    it could achieve high hardware reliability, perhaps through
  288.    redundancy.  The mail server could be used from arbitrary locations,
  289.    allowing users to read mail across campus, town, or country using
  290.    more and more commonly available clients.  Furthermore, the same user
  291.    may access his mailbox from different clients at different times, and
  292.    multiple users may access the same mailbox simultaneously.
  293.  
  294.    The mail server acts an an interface among users, data storage, and
  295.    other mailers.  The mail access protocol is used to retrieve
  296.    messages, access and change properties of messages, and manage
  297.    mailboxes.  This differs from some approaches (e.g., Unix mail via
  298.    NFS) in that the mail access protocol is used for all message
  299.    manipulations, isolating the user and the client from all knowledge
  300.    of how the data storage is used.  This means that the mail server can
  301.    utilize the data storage in whatever way is most efficient to
  302.    organize the mail in that particular environment, without having to
  303.    worry about storage representation compatibility across different
  304.    machines.
  305.  
  306.    In defining a mail access protocol, it is important to keep in mind
  307.    that the client and server form a macrosystem, in which it should be
  308.    possible to exploit the strong points of both while compensating for
  309.    each other's weaknesses.  Furthermore, it's desirable to allow for a
  310.    growth path beyond the hoary text-only RFC 822 protocol.  Unlike
  311.    POP2, IMAP3 has extensive features for remote searching and parsing
  312.    of messages on the server.  For example, a free text search
  313.    (optionally in conjunction with other searching) can be made
  314.    throughout the entire mailbox by the server and the results made
  315.    available to the client without the client having to transfer the
  316.    entire mailbox and searching itself.  Since remote parsing of a
  317.    message into a structured (and standard format) "envelope" is
  318.    available, a client can display envelope information and implement
  319.    commands such as REPLY without having any understanding of how to
  320.    parse RFC 822, etc., headers.
  321.  
  322.    Additionally, IMAP3 offers several facilities for managing a mailbox
  323.    beyond the simple "delete message" functionality of POP2.
  324.  
  325.    In spite of this, IMAP3 is a relatively simple protocol.  Although
  326.    servers should implement the full set of IMAP3 functions, a simple
  327.    client can be written which uses IMAP3 in much the way as a POP2
  328.    client.
  329.  
  330.    IMAP3 differs from the DMSP protocol of PCMAIL (RFC 1056) in a more
  331.    fundamental manner, reflecting the differing architectures of IMAP
  332.    and PCMAIL.  PCMAIL is either an online ("interactive mode"), or
  333.    offline ("batch mode") system.  IMAP is primarily an online system in
  334.    which real-time and simultaneous mail access were considered
  335.  
  336.  
  337.  
  338. Rice                                                            [Page 6]
  339.  
  340. RFC 1203                         IMAP3                     February 1991
  341.  
  342.  
  343.    important.
  344.  
  345.    In PCMAIL, there is a long-term client/server relationship in which
  346.    some mailbox state is preserved on the client.  There is a
  347.    registration of clients used by a particular user, and the client
  348.    keeps a set of "descriptors" for each message which summarize the
  349.    message.  The server and client synchronize their states when the
  350.    DMSP connection starts up, and, if a client has not accessed the
  351.    server for a while, the client does a complete reset (reload) of its
  352.    state from the server.
  353.  
  354.    In IMAP, the client/server relationship lasts only for the duration
  355.    of the IMAP3 connection.  All mailbox state is maintained on the
  356.    server.  There is no registration of clients.  The function of a
  357.    descriptor is handled by a structured representation of the message
  358.    "envelope".  This structure makes it unnecessary for a client to know
  359.    anything about RFC 822 parsing.  There is no synchronization since
  360.    the client does not remember state between IMAP3 connections.  This
  361.    is not a problem since in general the client never needs the entire
  362.    state of the mailbox in a single session, therefore there isn't much
  363.    overhead in fetching the state information that is needed as it is
  364.    needed.
  365.  
  366.    There are also some functional differences between IMAP3 and DMSP.
  367.    DMSP has functions for sending messages, printing messages, and
  368.    changing passwords, all of which are done outside of IMAP3.  DMSP has
  369.    16 binary flags of which 8 are defined by the system.  IMAP has flag
  370.    names; there are currently 5 defined system flag names and a facility
  371.    for some number (29 in the current implementations) of user flag
  372.    names.  IMAP3 has a sophisticated message search facility in the
  373.    server to identify interesting messages based on dates, addresses,
  374.    flag status, or textual contents without compelling the client to
  375.    fetch this data for every message.
  376.  
  377.    It was felt that maintaining state on the client is advantageous only
  378.    in those cases where the client is only used by a single user, or if
  379.    there is some means on the client to restrict access to another
  380.    user's data.  It can be a serious disadvantage in an environment in
  381.    which multiple users routinely use the same client, the same user
  382.    routinely uses different clients, and where there are no access
  383.    restrictions on the client.  It was also observed that most user mail
  384.    access is to a relatively small set of "interesting" messages, which
  385.    were either "new" mail or mail based upon some user-selected
  386.    criteria. Consequently, IMAP3 was designed to easily identify those
  387.    "interesting" messages so that the client could fetch the state of
  388.    those messages and not those that were not "interesting".
  389.  
  390.    One crucial philosophical difference between IMAP and other common
  391.  
  392.  
  393.  
  394. Rice                                                            [Page 7]
  395.  
  396. RFC 1203                         IMAP3                     February 1991
  397.  
  398.  
  399.    mail protocols is that IMAP is a mailbox access protocol, not a
  400.    protocol for manipulating mail files.  In the IMAP model, unlike
  401.    other mail system models in which mail is stored in a linear mail
  402.    file, no specification is made for the implementation architecture
  403.    for mail storage.  Servers may choose to implement mailboxes as files
  404.    but this is a detail of which the client can be totally unaware.
  405.  
  406.    What is more, in the IMAP model, mailboxes are viewed as mappings
  407.    from keys into values.  There are broadly three types of keys,
  408.    generic, canonical and concrete.  Generic keys are generic, mail
  409.    protocol independent keys defined by IMAP which are meaningful across
  410.    multiple mail encoding formats.  An example of such a generic key
  411.    might be "TO", which would be associated with the "To:" field of an
  412.    RFC 822 format message.
  413.  
  414.    Canonical keys represent the way in which the server can associate
  415.    values that are generally "about" a certain key concept, possibly
  416.    integrating several mail format specific fields, without having to
  417.    worry the client with the particular details of any particular
  418.    message format.  Thus, the canonical TO key (called $TO) could denote
  419.    anything that could reasonably be construed as being directed towards
  420.    someone.  Hence, in an RFC 822 message the server could find the
  421.    union of the "To:", "Resent-To", "Apparently-To:" and "CC:" fields to
  422.    be the appropriate value associated with the canonical $TO key.
  423.  
  424.    Concrete keys allow the client to gain access to certain mail format
  425.    specific concepts, that are not pre-specified by the IMAP protocol,
  426.    in a well defined manner.  For example, If the client asks for the
  427.    value associated with the "APPARENTLY-TO" key then, if the message
  428.    were to be in RFC 822 format, the server would look for a header
  429.    field called "Apparently-To:".  If no such field is found or the
  430.    field is not implemented or meaningful for the particular message
  431.    format then the server will respond with the null value, called NIL,
  432.    indicating the non-existence of the field.
  433.  
  434.    Thus, IMAP servers are at liberty to implement mailboxes as a
  435.    relational databases if it seems convenient.  Indeed, we anticipate
  436.    that future mail systems will tend to use database technology for the
  437.    storage and indexing of mailboxes as a result of the pressure caused
  438.    by the increasing size of mailboxes.
  439.  
  440.    Although for historical reasons IMAP is currently somewhat closely
  441.    associated with RFC 822, we anticipate that future developments in
  442.    IMAP will remove these mail format specific components and will move
  443.    towards the generic model mentioned above.  This will allow IMAP more
  444.    easily to incorporate such things as multi-media mail.
  445.  
  446.  
  447.  
  448.  
  449.  
  450. Rice                                                            [Page 8]
  451.  
  452. RFC 1203                         IMAP3                     February 1991
  453.  
  454.  
  455. The Protocol
  456.  
  457.    The IMAP3 protocol consists of a sequence of client commands and
  458.    server responses to those commands, with extra information from the
  459.    server data being sent asynchronously to and independent to the
  460.    responses to client commands.  Unlike most Internet protocols,
  461.    commands and responses are tagged.  That is, a command begins with a
  462.    unique identifier (typically a short alphanumeric sequence such as a
  463.    Lisp "gensym" function would generate e.g., A0001, A0002, etc.),
  464.    called a tag.  The response to this command is given the same tag
  465.    from the server.
  466.  
  467.    We distinguish between data sent by the server as the result of a
  468.    client request, which we term "SOLICITED" and data sent by the server
  469.    not as the result of a client request, which we term "UNSOLICITED".
  470.    The server may send unsolicited data at any time that would not
  471.    fragment another piece of data on the same stream rendering it
  472.    unintelligible.  The server is contractually required, however, to
  473.    return all data that is solicited by the client before the return of
  474.    the completion signal for that command, i.e., all solicited data must
  475.    be returned within the temporal extent of the request/completion
  476.    acknowledgement wrapper.  This does not, however, preclude the
  477.    simultaneous processing of multiple requests by the client, it simply
  478.    requires that the client be confident that it has all the requested
  479.    data when a request finishes.  This allows the implementation of both
  480.    synchronous and asynchronous clients.
  481.  
  482.    Solicited data is identified by the tag of the initial request by the
  483.    client.  Unsolicited data is identified by the special reserved tag
  484.    of "*".  There is another special reserved tag, "+", discussed below.
  485.  
  486.    Note: the tagging of SOLICITED data is only permitted for a selected
  487.    server version other than 2.0.
  488.  
  489.    No assumptions concerning serial or monolithic processing by the
  490.    server can be made by a correct client.  The server is at liberty to
  491.    process multiple requests by the same client in any order.  This
  492.    allows servers to process costly searches over mailboxes on slow
  493.    backing storage media in the background, while still preserving
  494.    interactive performance.  Clients can, however, assume the
  495.    serialization of the request/data/completion behavior mentioned
  496.    above.
  497.  
  498.    When a connection is opened the server sends an unsolicited OK
  499.    response as a greeting message and then waits for commands.  When
  500.    commands are received the server acts on them and responds with
  501.    responses, often interspersed with data.
  502.  
  503.  
  504.  
  505.  
  506. Rice                                                            [Page 9]
  507.  
  508. RFC 1203                         IMAP3                     February 1991
  509.  
  510.  
  511.    The client opens a connection, waits for the greeting, then sends a
  512.    LOGIN command with user name and password arguments to establish
  513.    authorization.  Following an OK response from the server, the client
  514.    then sends a SELECT command to access the desired mailbox.  The
  515.    user's default mailbox has a special reserved name of "INBOX" which
  516.    is independent of the operating system that the server is implemented
  517.    on.  The server will generally send a list of valid flags, number of
  518.    messages, and number of messages arrived since last access for this
  519.    mailbox as solicited data, followed by an OK response.  The client
  520.    may terminate access to this mailbox and access a different one with
  521.    another SELECT command.
  522.  
  523.    Because the SELECT command affects the state of the server in a
  524.    fundamental way, the server is required to process all outstanding
  525.    commands for any given mailbox before sending the OK tag for the
  526.    SELECT command.  Thus, the client will always know that all responses
  527.    before an OK SELECT response will refer to the old mailbox and all
  528.    responses following it will apply to the new mailbox.
  529.  
  530.    Because, in the real world, local needs or experimental work will
  531.    dictate that servers will support both supersets of the defined
  532.    behavior and incompatible changes, servers will support a
  533.    SELECT.VERSION command and a SELECT.FEATURES command, the purpose of
  534.    which is to allow clients to select the overall behavior and specific
  535.    features that they want from a server.  The default behavior of any
  536.    server is to process commands and to have interaction syntax the same
  537.    as is specified by IMAP2 in RFC 1064.  A server may not behave in any
  538.    other manner unless the SELECT.VERSION or SELECT.FEATURES commands
  539.    are used to select different behavior.
  540.  
  541.    Over time, when groups of generally useful changes to the current,
  542.    default behavior of the server are found, these will be collected
  543.    together and incorporated in such a way that all of the features can
  544.    be selected simply by selecting a particular major version number of
  545.    the protocol.  It should be noted that the version numbers (both
  546.    major and minor) selected by the SELECT.VERSION command denote
  547.    versions of the IMAP protocol, not versions of the server per se.
  548.    Thus, although in general changes to the protocol specification will
  549.    be made in such a way that they are upwards compatible, this cannot
  550.    be guaranteed.  No client should rely on tests of the form "if
  551.    major_version > 2 then..." being valid for all protocol versions,
  552.    since incompatible changes might be made in the future.
  553.  
  554.    The client reads mailbox information by means of FETCH commands.  The
  555.    actual data is transmitted via the solicited data mechanism (that is,
  556.    FETCH should be viewed as poking the server to include the desired
  557.    data along with any other data it wishes to transmit to the client).
  558.    There are three major categories of data which may be fetched.
  559.  
  560.  
  561.  
  562. Rice                                                           [Page 10]
  563.  
  564. RFC 1203                         IMAP3                     February 1991
  565.  
  566.  
  567.    The first category is that data which is associated with a message as
  568.    an entity in the mailbox.  There are presently three such items of
  569.    data: the "internal date", the "RFC 822 size", and the "flags".  The
  570.    internal date is the date and time that the message was placed in the
  571.    mailbox.  The RFC 822 size is subject to deletion in the future; it
  572.    is the size in bytes of the message, expressed as an RFC 822 text
  573.    string.  Current clients only use it as part of a status display
  574.    line.  The flags are a list of status flags associated with the
  575.    message (see below).  All of the first category data can be fetched
  576.    by using the macro-fetch word "FAST"; that is, "FAST" expands to
  577.    "(FLAGS INTERNALDATE RFC822.SIZE)".
  578.  
  579.    The second category is that data which describes the composition and
  580.    delivery information of a message; that is, information such as the
  581.    message sender, recipient lists, message-ID, subject, etc.  This is
  582.    the information which is stored in the message header in RFC 822
  583.    format message and is traditionally called the "envelope".  [Note:
  584.    this should not be confused with the SMTP (RFC 821) envelope, which
  585.    is strictly limited to delivery information.]  IMAP3 defines a
  586.    structured and unambiguous representation for the envelope which is
  587.    particularly nice for Lisp-based parsers.  A client can use the
  588.    envelope for operations such as replying and not worry about RFC 822
  589.    at all.  Envelopes are discussed in more detail below.  The first and
  590.    second category data can be fetched together by using the macro-fetch
  591.    word "ALL"; that is, "ALL" expands to "(FLAGS INTERNALDATE
  592.    RFC822.SIZE ENVELOPE)".
  593.  
  594.    The third category is that data which is intended for direct human
  595.    viewing.  The present RFC 822 based IMAP3 defines three such items:
  596.    RFC822.HEADER, RFC822.TEXT, and RFC822 (the latter being the two
  597.    former appended together in a single text string).  Fetching "RFC822"
  598.    is equivalent to typing the RFC 822 representation of the message as
  599.    stored on the mailbox without any filtering or processing.
  600.  
  601.    Typically, a client will "FETCH ALL" for some or all of the messages
  602.    in the mailbox for use as a presentation menu, and when the user
  603.     wishes to read a particular message will "FETCH RFC822.TEXT" to get
  604.    the message body.  A more primitive client could, of course, simply
  605.    "FETCH RFC822" a la POP2-type functionality.
  606.  
  607.    The client can alter certain data by means of a STORE command.  As an
  608.    example, a message is deleted from a mailbox by a STORE command which
  609.    includes the \DELETED flag as one of the flags being set.
  610.  
  611.    Other client operations include copying a message to another mailbox
  612.    (COPY command), permanently removing deleted messages (EXPUNGE
  613.    command), checking for new messages (CHECK command), and searching
  614.    for messages which match certain criteria (SEARCH command).
  615.  
  616.  
  617.  
  618. Rice                                                           [Page 11]
  619.  
  620. RFC 1203                         IMAP3                     February 1991
  621.  
  622.  
  623.    The client terminates the session with the LOGOUT command.  The
  624.    server returns a "BYE" followed by an "OK".
  625.  
  626. A Typical Scenario
  627.  
  628.         Client                          Server
  629.         ------                          ------
  630.                                     {Wait for Connection}
  631.     {Open Connection}        -->
  632.                                 <-- * OK IMAP3 Server Ready
  633.                                     {Wait for command}
  634.     A001 SUPPORTED.VERSIONS   -->
  635.                                 <-- * SUPPORTED.VERSIONS ((2 0 )
  636.                                         (3 0 EIGHT.BIT.TRANSPARENT
  637.                                              AUTO.SET.SEEN
  638.                                              TAGGED.SOLICITED))
  639.                                     A001 OK Supported Versions returned.
  640.                                     {Wait for command}
  641.     A002 SELECT.VERSION (3 0) -->
  642.                                 <-- A002 OK Version 3.0 Selected.
  643.                                     {Wait for command}
  644.     A002 SELECT.FEATURES TAGGED.SOLICITED -->
  645.                                 <-- A002 OK Features selected.
  646.                                     {Wait for command}
  647.     A003 LOGIN Fred Secret   -->
  648.                                 <-- A003 OK User Fred logged in
  649.                                     {Wait for command}
  650.     A004 SELECT INBOX        -->
  651.                                 <-- A004 FLAGS (Meeting Notice \Answered
  652.                                              \Flagged \Deleted \Seen)
  653.                                 <-- A004 19 EXISTS
  654.                                 <-- A004 2 RECENT
  655.                                 <-- A004 OK Select complete
  656.                                     {Wait for command}
  657.     A005 FETCH 1:19 ALL      -->
  658.                                 <-- A005 1 Fetch (......)
  659.                                         ...
  660.                                 <-- A005 18 Fetch (......)
  661.                                 <-- A005 19 Fetch (......)
  662.                                 <-- A005 OK Fetch complete
  663.                                     {Wait for command}
  664.     A006 FETCH 8 RFC822.TEXT -->
  665.                                 <-- A006 8 Fetch (RFC822.TEXT {893}
  666.                                        ...893 characters of text...
  667.                                 <-- )
  668.                                 <-- A006 OK Fetch complete
  669.                                     {Wait for command}
  670.  
  671.  
  672.  
  673.  
  674. Rice                                                           [Page 12]
  675.  
  676. RFC 1203                         IMAP3                     February 1991
  677.  
  678.  
  679.     A007 STORE 8 +Flags \Deleted -->
  680.                                 <-- A007 8 Store (Flags (\Deleted
  681.                                                \Seen))
  682.                                 <-- A007 OK Store complete
  683.                                     {Wait for command}
  684.     A008 EXPUNGE             -->
  685.                                 <-- A008 19 EXISTS
  686.                                 <-- A008 8 EXPUNGE
  687.                                 <-- A008 18 EXISTS
  688.                                 <-- A008 Expunge complete
  689.                                     {Wait for command}
  690.     A009 LOGOUT              -->
  691.                                 <-- A009 BYE IMAP3 server quitting
  692.                                 <-- A009 OK Logout complete
  693.     {Close Connection}       --><-- {Close connection}
  694.                                     {Go back to start}
  695.  
  696.    A more complex scenario produced by a pipelining multiprocess client.
  697.  
  698.         Client                          Server
  699.         ------                          ------
  700.                                     {Wait for Connection}
  701.     {Open session as above}
  702.                                 <-- A004 19 EXISTS
  703.                                 <-- A004 2 RECENT
  704.                                 <-- A004 OK Select complete
  705.                                     {Wait for command}
  706.     A005 SEARCH RECENT       -->
  707.                                 <-- A005 SEARCH (18 19) (RECENT)
  708.                                 <---A005 OK Search complete
  709.     A006 FETCH 18:19 ALL RFC822.TEXT
  710.     A007 STORE 18:19 +FLAGS (\SEEN)
  711.     A008 FETCH 1:17 ALL      -->
  712.                                 <-- A006 18 Fetch (... RFC822.TEXT ...)
  713.     A009 STORE 18 +FLAGS (\DELETED)
  714.                                 <-- A006 19 Fetch (... RFC822.TEXT ...)
  715.                                 <-- A006 OK Fetch complete
  716.                                 <-- A007 18 STORE (Flags (\Seen))
  717.     A010 STORE 19 +FLAGS (\DELETED)
  718.                                 <-- A007 19 STORE (Flags (\Seen))
  719.                                 <-- A007 OK Store complete
  720.                                 <-- A008 1 Fetch (......)
  721.                                        ...
  722.                                 <-- A008 16 Fetch (......)
  723.                                 <-- A008 17 Fetch (......)
  724.                                 <-- A008 OK Fetch complete
  725.                                 <-- A009 18 STORE (Flags (\Seen
  726.                                                           \Deleted))
  727.  
  728.  
  729.  
  730. Rice                                                           [Page 13]
  731.  
  732. RFC 1203                         IMAP3                     February 1991
  733.  
  734.  
  735.                                 <-- A009 OK Store complete
  736.                                 <-- A010 19 STORE (Flags (\Seen
  737.                                                           \Deleted))
  738.                                 <-- A010 OK Store complete
  739.                                     {Wait for command}
  740.                                 <-- * EXISTS 23
  741.                                 <-- * RECENT 4
  742.                                 <-- * SEARCH (20 21 22 23) (RECENT)
  743.    A011 FETCH 20:23 ALL RFC822.TEXT
  744.  
  745. Conventions
  746.  
  747.    The following terms are used in a meta-sense in the syntax
  748.    specification below:
  749.  
  750.       An ASCII-STRING is a sequence of arbitrary ASCII characters.
  751.  
  752.       An ATOM is a sequence of ASCII characters delimited by SP or CRLF.
  753.  
  754.       A CHARACTER is any ASCII character except """", "{", CR, LF, "%",
  755.       or "\".
  756.  
  757.       A CRLF is an ASCII carriage-return character followed immediately
  758.       by an ASCII linefeed character.
  759.  
  760.       A NUMBER is a sequence of the ASCII characters which represent
  761.       decimal numerals ("0" through "9"), delimited by SP, CRLF, ",", or
  762.       ":".
  763.  
  764.       A SP is the ASCII space character.
  765.  
  766.       A TEXT_LINE is a human-readable sequence of ASCII characters up to
  767.       but not including a terminating CRLF.
  768.  
  769.    One of the most common fields in the IMAP3 protocol is a STRING,
  770.    which may be an ATOM, QUOTED-STRING (a sequence of CHARACTERs inside
  771.    double-quotes), or a LITERAL.  A literal consists of an open brace
  772.    ("{"), a number, a close brace ("}"), a CRLF, and then an ASCII-
  773.    STRING of n characters, where n is the value of the number inside the
  774.    brace. In general, a string should be represented as an ATOM or
  775.    QUOTED-STRING if at all possible.  The semantics for QUOTED-STRING or
  776.    LITERAL are checked before those for ATOM; therefore an ATOM used in
  777.    a STRING may only contain CHARACTERs.  Literals are most often sent
  778.    from the server to the client; in the rare case of a client to server
  779.    literal there is a special consideration (see the "+ text" response
  780.    below).
  781.  
  782.    Another important field is the SEQUENCE, which identifies a set of
  783.  
  784.  
  785.  
  786. Rice                                                           [Page 14]
  787.  
  788. RFC 1203                         IMAP3                     February 1991
  789.  
  790.  
  791.    messages by consecutive numbers from 1 to n where n is the number of
  792.    messages in the mailbox.  A sequence may consist of a single number,
  793.    a pair of numbers delimited by colon indicating all numbers between
  794.    those two numbers, or a list of single numbers and/or number pairs.
  795.    For example, the sequence 2,4:7,9,12:15 is equivalent to
  796.    2,4,5,6,7,9,12,13,14,15 and identifies all of those messages.
  797.  
  798. Definitions of Commands and Responses
  799.  
  800.    Summary of Commands and Responses
  801.  
  802. Commands:
  803.        tag NOOP
  804.        tag LOGIN user password
  805.        tag LOGOUT
  806.        tag SELECT mailbox
  807.        tag CHECK
  808.        tag EXPUNGE
  809.        tag COPY sequence mailbox
  810.        tag FETCH sequence data
  811.        tag STORE sequence data value
  812.        tag SEARCH criteria
  813.        tag BBOARD bboard
  814.        tag FIND (BBOARDS / MAILBOXES) pattern
  815.        tag READONLY
  816.        tag READWRITE
  817.        tag SELECT.VERSION (major_version minor_version)
  818.        tag SELECT.FEATURES features
  819.        tag SUPPORTED.VERSIONS
  820.        tag FLAGS
  821.        tag SET.FLAGS
  822.  
  823. Responses (can be either solicited or unsolicited):
  824.        */tag FLAGS flag_list
  825.        */tag SEARCH (numbers) (criteria)
  826.        */tag EXISTS
  827.        */tag RECENT
  828.        */tag EXPUNGE
  829.        */tag STORE data
  830.        */tag FETCH data
  831.        */tag BBOARD bboard_name
  832.        */tag MAILBOX non_inbox_mailbox_name
  833.        */tag SUPPORTED.VERSIONS version_data
  834.        */tag READONLY
  835.        */tag READWRITE
  836.        */tag OK text
  837.        */tag NO text
  838.        */tag BAD text
  839.  
  840.  
  841.  
  842. Rice                                                           [Page 15]
  843.  
  844. RFC 1203                         IMAP3                     February 1991
  845.  
  846.  
  847.        */tag BYE text
  848.  
  849. Responses (can only be solicited):
  850.        tag COPY message_number
  851.  
  852. Responses (can only be unsolicited):
  853.        + text
  854.  
  855. Commands
  856.  
  857.    tag NOOP
  858.  
  859.       The NOOP command returns an OK to the client.  By itself, it does
  860.       nothing, but certain things may happen as side effects.  For
  861.       example, server implementations which implicitly check the mailbox
  862.       for new mail may do so as a result of this command.  The primary
  863.       use of this command is to for the client to see if the server is
  864.       still alive (and notify the server that the client is still alive,
  865.       for those servers which have inactivity autologout timers).
  866.  
  867.    tag LOGIN user password
  868.  
  869.       The LOGIN command identifies the user to the server and carries
  870.       the password authenticating this user.  This information is used
  871.       by the server to control access to the mailboxes.
  872.  
  873.       EXAMPLE: A001 LOGIN SMITH SESAME logs in as user SMITH with
  874.       password SESAME.
  875.  
  876.    tag LOGOUT
  877.  
  878.       The LOGOUT command indicates the client is done with the session.
  879.       The server sends a solicited BYE response before the (tagged) OK
  880.       response, and then closes the connection.
  881.  
  882.    tag SELECT mailbox
  883.  
  884.       The SELECT command selects a particular mailbox.  The server must
  885.       check that the user is permitted read access to this mailbox.
  886.       Prior to returning an OK to the client, the server must send an
  887.       solicited FLAGS and <n> EXISTS response to the client giving the
  888.       flags list for this mailbox (simply the system flags if this
  889.       mailbox doesn't have any special flags) and the number of messages
  890.       in the mailbox.  It is also recommended that the server send a <n>
  891.       RECENT unsolicited response to the client for the benefit of
  892.       clients which make use of the number of new messages in a mailbox.
  893.       It is further recommended that servers should send an unsolicited
  894.       READONLY message if the mailbox that has been selected is not
  895.  
  896.  
  897.  
  898. Rice                                                           [Page 16]
  899.  
  900. RFC 1203                         IMAP3                     February 1991
  901.  
  902.  
  903.       writable by the user.
  904.  
  905.       Multiple SELECT commands are permitted in a session, in which case
  906.       the prior mailbox is deselected first.
  907.  
  908.       The default mailbox for the SELECT command is INBOX, which is a
  909.       special name reserved to mean "the primary mailbox for this user
  910.       on this server".  The format of other mailbox names is operating
  911.       system dependent (as of this writing, it reflects the path of the
  912.       mailbox on the current servers), though it could reflect any
  913.       server-specific naming convention for the namespace of mailboxes.
  914.       Such a namespace need not and should not be viewed as being
  915.       equivalent or linked to the server machine's file system.
  916.  
  917.       EXAMPLES: A002 SELECT INBOX  ;; selects the default mailbox.
  918.                 A002 197 EXISTS    ;; server says 197 messages in INBOX
  919.                 A002 5 RECENT      ;; server says 5 are recent.
  920.                 A002 OK Select complete.
  921.       or
  922.                 A003 SELECT /usr/fred/my-mail.txt
  923.                  ;; select a different user specified mailbox.
  924.                 ...
  925.  
  926.    tag CHECK
  927.  
  928.       The CHECK command forces a check for new messages and a rescan of
  929.       the mailbox for internal change for those implementations which
  930.       allow multiple simultaneous read/write access to the same mailbox
  931.       (e.g., TOPS-20).  It is recommend that periodic implicit checks
  932.       for new mail be done by servers as well.  The server must send a
  933.       solicited <n> EXISTS response prior to returning an OK to the
  934.       client.
  935.  
  936.    tag EXPUNGE
  937.  
  938.       The EXPUNGE command permanently removes all messages with the
  939.       \DELETED flag set in its flags from the mailbox.  Prior to
  940.       returning an OK to the client, for each message which is removed,
  941.       a solicited <n> EXPUNGE response is sent indicating which message
  942.       was removed.  The message number of each subsequent message in the
  943.       mailbox is immediately decremented by 1; this means that if the
  944.       last 5 messages in a 9-message mailbox are expunged you will
  945.       receive 5 "5 EXPUNGE" responses for message 5.  To ensure mailbox
  946.       integrity and server/client synchronization, it is recommended
  947.       that the server do an implicit check prior to commencing the
  948.       expunge and again when the expunge is completed.  Furthermore, if
  949.       the server allows multiple simultaneous access to the same mailbox
  950.       the server must guarantee both the integrity of the mailbox and
  951.  
  952.  
  953.  
  954. Rice                                                           [Page 17]
  955.  
  956. RFC 1203                         IMAP3                     February 1991
  957.  
  958.  
  959.       the views of it held by the clients.
  960.  
  961.       EXPUNGE is not allowed if the user does not have write access to
  962.       this mailbox.  If a user does not have write access to the mailbox
  963.       then the server is required to signal this fact by replying with a
  964.       NO response with a suitable text string that can be presented to
  965.       the user explaining that the mailbox is read-only.  It is further
  966.       recommended that servers send an unsolicited READONLY message to
  967.       clients that attempt an expunge operation on a read only mailbox.
  968.  
  969.    tag COPY sequence mailbox
  970.  
  971.       The COPY command copies the specified message(s) to the specified
  972.       destination mailbox.  If the destination mailbox does not exist,
  973.       the server should create it.  Prior to returning an OK to the
  974.       client, the server must return a solicited <n> COPY response for
  975.       each message copied.
  976.  
  977.       EXAMPLE: A003 COPY 2:4 MEETING copies messages 2, 3, and 4 to
  978.       mailbox "MEETING".
  979.  
  980.       COPY is not allowed if the user does not have write access to the
  981.       destination mailbox.  If a user does not have write access to the
  982.       destination mailbox then the server is required to signal this
  983.       fact by replying with a NO response with a suitable text string
  984.       that can be presented to the user explaining that the mailbox is
  985.       read-only.  It is further recommended that servers send an
  986.       unsolicited READONLY message to clients that attempt to copy to a
  987.       read only mailbox.  IMAP3 does not specify "where" the message
  988.       will be put in the mailbox to which it has been copied.
  989.  
  990.    tag FETCH sequence fetch_att
  991.  
  992.       The FETCH command retrieves data associated with a message in the
  993.       mailbox.  The data items to be fetched may be either a single atom
  994.       or an S-expression list.  The attributes that can be fetched are
  995.       any of those mentioned specifically below along with any generic,
  996.       canonical or concrete key.  The set of predefined generic keys is:
  997.       {BCC, BODY, CC, FROM, HEADER, SIZE, SUBJECT, TEXT, TO}.  The set
  998.       of predefined canonical keys is {$CC, $FROM, $SUBJECT, $TO}.  The
  999.       value returned by the server for a non-existent or non-meaningful
  1000.       key is defined to be the null value, NIL.
  1001.  
  1002.       ALL             Equivalent to:
  1003.                       (FLAGS INTERNALDATE RFC822.SIZE ENVELOPE)
  1004.  
  1005.       ENVELOPE        The envelope of the message.  The envelope is
  1006.                       computed by the server by parsing the header,
  1007.  
  1008.  
  1009.  
  1010. Rice                                                           [Page 18]
  1011.  
  1012. RFC 1203                         IMAP3                     February 1991
  1013.  
  1014.  
  1015.                       i.e., the RFC 822 header for an RFC822 format
  1016.                       message, into the component parts, defaulting
  1017.                       various fields as necessary.
  1018.  
  1019.       FAST            Macro equivalent to:
  1020.                       (FLAGS INTERNALDATE RFC822.SIZE)
  1021.  
  1022.       FLAGS           The flags which are set for this message.
  1023.                       This may include the following system flags:
  1024.  
  1025.                               \RECENT    Message arrived since
  1026.                                           last read of this mailbox
  1027.                               \SEEN      Message has been read
  1028.                               \ANSWERED  Message has been answered
  1029.                               \FLAGGED   Message is "flagged" for
  1030.                                           urgent/special attention
  1031.                               \DELETED   Message is "deleted" for
  1032.                                           removal by later EXPUNGE
  1033.  
  1034.       INTERNALDATE    The date and time the message was written to
  1035.                       the mailbox.
  1036.  
  1037.       RFC822          The message in RFC 822 format.
  1038.  
  1039.       RFC822.HEADER   The RFC 822 format header of the message.
  1040.  
  1041.       RFC822.SIZE     The number of characters in the message as
  1042.                       expressed in RFC 822 format.
  1043.  
  1044.       RFC822.TEXT     The text body of the message, omitting the
  1045.                       RFC 822 header.
  1046.  
  1047.       EXAMPLES:
  1048.  
  1049.       A003 FETCH 2:4 ALL
  1050.          fetches the flags, internal date, RFC 822 size, and envelope
  1051.          for messages 2, 3, and 4.
  1052.  
  1053.       A004 FETCH 3 RFC822
  1054.          fetches the RFC 822 representation for message 3.
  1055.  
  1056.       A005 FETCH 4 (FLAGS RFC822.HEADER)
  1057.          fetches the flags and RFC 822 format header for message 4.
  1058.  
  1059.       A006 FETCH 42 $SUBJECT
  1060.       A006 FETCH $SUBJECT "Some subject text..."
  1061.       A006 OK FETCH completed ok.
  1062.          fetches the canonical subject field.
  1063.  
  1064.  
  1065.  
  1066. Rice                                                           [Page 19]
  1067.  
  1068. RFC 1203                         IMAP3                     February 1991
  1069.  
  1070.  
  1071.       A007 FETCH 42 APPARENTLY-TO
  1072.       A007 FETCH APPARENTLY-TO NIL
  1073.       A007 OK FETCH found no value.
  1074.          fetches the concrete apparently-to field.
  1075.  
  1076.    tag STORE sequence data value
  1077.  
  1078.       The STORE command alters the values associated with particular
  1079.       keys for a message in the mailbox.  As is the case for the FETCH
  1080.       command, any generic, canonical or concrete key may be used to
  1081.       index the value provided.  In addition to these, the following
  1082.       pre-defined keys are provided.
  1083.  
  1084.    FLAGS           Replace the flags for the message with the
  1085.                    argument (in flag list format).
  1086.                   The server must respond with a solicited STORE FLAGS
  1087.                   message, showing the new state of the flags after
  1088.                   the store.
  1089.  
  1090.    +FLAGS          Add the flags in the argument to the
  1091.                    message's flag list.
  1092.                  The server must respond with a solicited STORE FLAGS
  1093.                  message, showing the new state of the flags after
  1094.                  the store.
  1095.  
  1096.   -FLAGS          Remove the flags in the argument from the
  1097.                   message's flag list.
  1098.                  The server must respond with a solicited STORE FLAGS
  1099.                  message, showing the new state of the flags after
  1100.                  the store.
  1101.  
  1102.   RFC822.HEADER   Replace the header of the message(s) with that
  1103.                   specified.  This allows users to use their mailboxes
  1104.                   as databases with header fields as keys.
  1105.                   The server must respond with solicited
  1106.                   STORE RFC822.HEADER, STORE RFC822.SIZE and
  1107.                   STORE ENVELOPE messages,  showing the new state
  1108.                   of the reparsed header after the store.
  1109.  
  1110.   RFC822.TEXT     Replace the body of the messages with that specified.
  1111.                   The server must respond with solicited
  1112.                   STORE RFC822.TEXT and STORE RFC822.SIZE messages,
  1113.                   showing the new state of the message after the store.
  1114.  
  1115.          STORE is not allowed if the user does not have write access to
  1116.          this mailbox.
  1117.  
  1118.          The server is required to send a solicited STORE response for
  1119.  
  1120.  
  1121.  
  1122. Rice                                                           [Page 20]
  1123.  
  1124. RFC 1203                         IMAP3                     February 1991
  1125.  
  1126.  
  1127.          each store operation that results in a format transformation by
  1128.          the server.  For example, the server is required to send a
  1129.          STORE FLAGS response when the client performs a STORE +FLAGS or
  1130.          a STORE -FLAGS, since the client may not easily be able to know
  1131.          what the result of this command will be.  Similarly, if the
  1132.          client emits a STORE FROM command then the server should
  1133.          respond with a suitable STORE FROM response because the client
  1134.          would be sending a string value to be stored and the server
  1135.          should transform this into a set of addresses.  In general,
  1136.          however, although it is legal for the server to send a
  1137.          solicited STORE response for each STORE operation, this is
  1138.          discouraged, since it might result in the retransmission of
  1139.          very large and unnecessary amounts of data that have been
  1140.          stored.
  1141.  
  1142.          EXAMPLE: A003 STORE 2:4 +FLAGS (\DELETED) marks messages 2, 3,
  1143.          and 4 for deletion.
  1144.  
  1145.    tag SEARCH search_criteria
  1146.  
  1147.       The SEARCH command searches the mailbox for messages which match
  1148.       the given set of criteria.  The server response SEARCH (criteria)
  1149.       (numbers) gives the set of messages which match the conjunction of
  1150.       the criteria specified.  In addition to each of the search
  1151.       criteria there is its logical inverse.  The logical inverse
  1152.       criterion is denoted by the ~ (tilda) sign.
  1153.  
  1154.       Thus, no message that matches the criterion:
  1155.          FROM crispin
  1156.  
  1157.       will match the criterion:
  1158.          ~FROM crispin
  1159.  
  1160.       The criteria for the search can be any generic, canonical or
  1161.       concrete key.  In addition to these, the following pre-defined
  1162.       keys are also provided:
  1163.  
  1164.       ALL             All messages in the mailbox; the default
  1165.                       initial criterion for ANDing.
  1166.  
  1167.       ANSWERED        Messages with the \ANSWERED flag set.
  1168.  
  1169.       BCC string      Messages which contain the specified string
  1170.                       in the envelope's BCC field.
  1171.  
  1172.       BEFORE date     Messages whose internal date is earlier than
  1173.                       the specified date.
  1174.  
  1175.  
  1176.  
  1177.  
  1178. Rice                                                           [Page 21]
  1179.  
  1180. RFC 1203                         IMAP3                     February 1991
  1181.  
  1182.  
  1183.       BODY string     Messages which contain the specified string
  1184.                       in the body of the message.
  1185.  
  1186.       CC string       Messages which contain the specified string
  1187.                       in the envelope's CC field.
  1188.  
  1189.       DELETED         Messages with the \DELETED flag set.
  1190.  
  1191.       FLAGGED         Messages with the \FLAGGED flag set.
  1192.  
  1193.       FROM string     Messages which contain the specified string
  1194.                       in the envelope's FROM field.
  1195.  
  1196.       HEADER string   Messages which contain the specified string
  1197.                       in the message header.
  1198.  
  1199.       KEYWORD flag    Messages with the specified flag set.
  1200.  
  1201.       NEW             Messages which have the \RECENT flag set but
  1202.                       not the \SEEN flag.  This is functionally
  1203.                       equivalent to "RECENT UNSEEN".
  1204.  
  1205.       OLD             Messages which do not have the \RECENT flag
  1206.                       set.
  1207.  
  1208.       ON date         Messages whose internal date is the same as
  1209.                       the specified date.
  1210.  
  1211.       RECENT          Messages which have the \RECENT flag set.
  1212.  
  1213.       SEEN            Messages which have the \SEEN flag set.
  1214.  
  1215.       SINCE date      Messages whose internal date is later than
  1216.                       the specified date.
  1217.  
  1218.       SUBJECT string  Messages which contain the specified string
  1219.                       in the envelope's SUBJECT field.
  1220.  
  1221.       TEXT string     Messages which contain the specified string.
  1222.  
  1223.       TO string       Messages which contain the specified string in
  1224.                       the envelope's TO field.
  1225.  
  1226.          EXAMPLE:  A003 SEARCH DELETED FROM "SMITH" SINCE 1-OCT-87
  1227.          returns the message numbers for all deleted messages from Smith
  1228.          that were placed in the mailbox since October 1, 1987.
  1229.  
  1230.       Implementation note:  The UNANSWERED, UNDELETED, UNFLAGGED,
  1231.  
  1232.  
  1233.  
  1234. Rice                                                           [Page 22]
  1235.  
  1236. RFC 1203                         IMAP3                     February 1991
  1237.  
  1238.  
  1239.       UNKEYWORD and UNSEEN criteria, described below, are preserved in
  1240.       IMAP3 for IMAP2 compatibility.  They are, however, considered
  1241.       obsolete and new Client programs are encouraged to use the ~
  1242.       notation for the logical inverses of search criteria with a view
  1243.       to the dropping of this outmoded syntax in later versions.
  1244.  
  1245.       UNANSWERED      Messages which do not have the \ANSWERED flag
  1246.                       set.
  1247.  
  1248.       UNDELETED       Messages which do not have the \DELETED flag
  1249.                       set.
  1250.  
  1251.       UNFLAGGED       Messages which do not have the \FLAGGED flag
  1252.                       set.
  1253.  
  1254.       UNKEYWORD flag  Messages which do not have the specified flag
  1255.                       set.
  1256.  
  1257.       UNSEEN          Messages which do not have the \SEEN flag set.
  1258.  
  1259.    tag READONLY
  1260.  
  1261.       The READONLY command indicates that the client wishes to make the
  1262.       mailbox read-only.  The server is required to reply with a
  1263.       solicited READONLY or READWRITE response.
  1264.  
  1265.    tag READWRITE
  1266.  
  1267.       The READWRITE command indicates that the client wishes to make the
  1268.       mailbox read-write.  The server is required to reply with a
  1269.       solicited READONLY or READWRITE response.
  1270.  
  1271.    tag SUPPORTED.VERSIONS
  1272.  
  1273.       The SUPPORTED.VERSIONS solicits from the server a
  1274.       SUPPORTED.VERSIONS message, which encapsulates information about
  1275.       which versions and features the server supports.
  1276.  
  1277.    tag SELECT.VERSION (major_version minor_version)
  1278.  
  1279.       The SELECT.VERSION command indicates that the client wishes to
  1280.       select certain behavior on the part of the server.  The major and
  1281.       minor versions indicate the specific version of the protocol being
  1282.       selected.
  1283.  
  1284.       EXAMPLE: A002 SELECT.VERSION (3 0)
  1285.  
  1286.       A client may not request a server version that is not supported by
  1287.  
  1288.  
  1289.  
  1290. Rice                                                           [Page 23]
  1291.  
  1292. RFC 1203                         IMAP3                     February 1991
  1293.  
  1294.  
  1295.       the server, i.e., which is specifically mentioned in the response
  1296.       to a SUPPORTED.VERSIONS command.  An attempt to do so by a client
  1297.       will result in a NO response from the server.  It is an error for
  1298.       the SELECT.VERSION command to be used after a mailbox has been
  1299.       selected.  The rationale for this is that for some server
  1300.       implementations it might be necessary to spawn separate programs
  1301.       to implement widely divergent protocol versions.  Thus, the client
  1302.       cannot be allowed to expect any server state to be preserved after
  1303.       the use of the SELECT.VERSION command.  The default version of all
  1304.       servers is 2.0, i.e., IMAP2 as defined by RFC 1064.
  1305.  
  1306.    tag SELECT.FEATURES 1#features
  1307.  
  1308.       The SELECT.FEATURES command indicates that the client wishes to
  1309.       select certain specific features on the part of the server. A
  1310.       client may not request a feature that is not supported by the
  1311.       server, i.e., one that is explicitly mentioned in the set of
  1312.       features for the selected version returned by the
  1313.       SUPPORTED.VERSIONS command.  An attempt to do so by a client will
  1314.       result in a NO response from the server.
  1315.  
  1316.       EXAMPLE: A002 SELECT.FEATURES AUTO.SET.SEEN ~TAGGED.SOLICITED
  1317.               EIGHT.BIT.TRANSPARENT
  1318.  
  1319.       i.e., select the set of features called AUTO.SET.SEEN and
  1320.       EIGHT.BIT.TRANSPARENT and deselect the feature called
  1321.       TAGGED.SOLICITED.  The use of the SELECT.FEATURES command
  1322.       completely resets the set of selected features.  Note:  These are
  1323.       only example feature names and are not necessarily supported by
  1324.       any server.  See the appendix on features for more information on
  1325.       features.  Note:  Some features, when present in the server, will
  1326.       cause the upwards compatible extension of the grammar, i.e., by
  1327.       adding extra commands.  The server is at liberty not to remove
  1328.       these upwards compatible extensions to the command tables when a
  1329.       feature is disabled.  Thus, it is an error for a client to rely on
  1330.       getting a NO or BAD response in any way, for instance to determine
  1331.       the selectedness or presence of a feature.
  1332.  
  1333.    tag BBOARD bboard
  1334.  
  1335.       The BBOARD command is equivalent to SELECT, except that its
  1336.       argument is a bulletin board (BBoard) name.  The format of a
  1337.       BBoard name is implementation specific, although it is strongly
  1338.       encouraged to use something that resembles a name in a generic
  1339.       sense and not a file or mailbox name on the particular system.
  1340.       There is no requirement that a BBoard name be a mailbox name or a
  1341.       file name (in particular, Unix netnews has a completely different
  1342.       namespace from mailbox or file names).
  1343.  
  1344.  
  1345.  
  1346. Rice                                                           [Page 24]
  1347.  
  1348. RFC 1203                         IMAP3                     February 1991
  1349.  
  1350.  
  1351.       The result from the BBOARD command is identical from that of the
  1352.       SELECT command.  For example, in the TOPS-20 server
  1353.       implementation, the command
  1354.          A0002 BBOARD FOO
  1355.       is exactly equivalent to the command
  1356.          A0002 SELECT POBOX:<BBOARD>FOO.TXT
  1357.          Note: the equivalence in this example is *not* required by the
  1358.          protocol, and merely reflects the fuzzy distinction between
  1359.          mailboxes and BBoards on TOPS-20.
  1360.  
  1361.    tag FIND (BBOARDS / MAILBOXES) pattern
  1362.  
  1363.       The FIND command accepts as arguments the keywords BBOARDS or
  1364.       MAILBOXES and a pattern which specifies some set of BBoard/mailbox
  1365.       names which are usable by the BBOARD/SELECT command.  Two wildcard
  1366.       characters are defined; "*" specifies that any number (including
  1367.       zero) characters may match at this position and "%" specifies that
  1368.       a single character may match at this position.  For example,
  1369.       FOO*BAR will match FOOBAR, FOOD.ON.THE.BAR and FOO.BAR, whereas
  1370.       FOO%BAR will match only FOO.BAR; furthermore, "*" will match all
  1371.       BBoards/mailboxes.  The following quoting convention applies to
  1372.       wildcards: "\*" is the literal "*" character, "\%" is the literal
  1373.       "%" character and "\\" is the literal "\" character.  Notes: The
  1374.       format of mailboxes is server implementation dependent.  The
  1375.       special mailbox name INBOX is not included in the output to the
  1376.       FIND MAILBOXES command.
  1377.  
  1378.       The FIND command solicits any number of BBOARD or MAILBOX
  1379.       responses from the server as appropriate.
  1380.  
  1381.       Examples:
  1382.           A0002 FIND BBOARDS *
  1383.           A0002 BBOARD FOOBAR
  1384.           A0002 BBOARD GENERAL
  1385.           A0002 OK FIND completed
  1386.       or
  1387.           A0002 FIND MAILBOXES FOO%BA*
  1388.           A0002 MAILBOX FOO.BAR
  1389.           A0002 MAILBOX FOO.BAZZAR
  1390.           A0002 OK FIND completed
  1391.  
  1392.       Note: Although the use of explicit file or path names for
  1393.       mailboxes is discouraged by this standard, it may be unavoidable.
  1394.       It is important that the value returned in the MAILBOX solicited
  1395.       reply be usable in the SELECT command without remembering any path
  1396.       specification which may have been used in the FIND MAILBOXES
  1397.       pattern.
  1398.  
  1399.  
  1400.  
  1401.  
  1402. Rice                                                           [Page 25]
  1403.  
  1404. RFC 1203                         IMAP3                     February 1991
  1405.  
  1406.  
  1407.    tag FLAGS
  1408.  
  1409.       The FLAGS command solicits a FLAGS response from the server.
  1410.  
  1411.    tag SET.FLAGS flag_list
  1412.  
  1413.       The SET.FLAGS command defines the user specifiable flags for this
  1414.       mailbox, i.e., the keywords.  If this set does not include flags
  1415.       formerly sent to the client by the server in a FLAGS message then
  1416.       this constitutes a request to delete the flag.  Any new flags
  1417.       should be created.  This command does not affect the system
  1418.       defined flags and any system flags that are included in the
  1419.       flag_list will be ignored.  The server must respond to this
  1420.       command with a solicited FLAGS message.  If the deletion of a flag
  1421.       results in the invalidation of the flag sets of any messages then
  1422.       the server is required to send solicited STORE FLAGS messages to
  1423.       the client for each modified message.
  1424.  
  1425. Responses:
  1426.  
  1427.    */tag OK text
  1428.  
  1429.       In its solicited form this response identifies successful
  1430.       completion of the command with the indicated tag.  The text is a
  1431.       line of human-readable text which may be useful in a protocol
  1432.       telemetry log for debugging purposes.
  1433.  
  1434.       In its unsolicited form, this response indicates simply that the
  1435.       server is alive.  No special action on the part of the client is
  1436.       called for.  This is presently only used by servers at startup as
  1437.       a greeting message indicating that they are ready to accept the
  1438.       first command.  This usage, although legal, is by no means
  1439.       required.  The text is a line of human-readable text which may be
  1440.       logged in protocol telemetry.
  1441.  
  1442.    */tag NO text
  1443.  
  1444.       In its solicited form this response identifies unsuccessful
  1445.       completion of the command with the indicated tag.  The text is a
  1446.       line of human-readable text which probably should be displayed to
  1447.       the user in an error report by the client.
  1448.  
  1449.       In its unsolicited form this response indicates some operational
  1450.       error at the server which cannot be traced to any protocol
  1451.       command.  The text is a line of human-readable text which should
  1452.       be logged in protocol telemetry for the maintainer of the server
  1453.       and/or the client.
  1454.  
  1455.  
  1456.  
  1457.  
  1458. Rice                                                           [Page 26]
  1459.  
  1460. RFC 1203                         IMAP3                     February 1991
  1461.  
  1462.  
  1463.    */tag BAD text
  1464.  
  1465.       In its solicited form response indicates faulty protocol received
  1466.       from the client and indicates a bug.  The text is a line of
  1467.       human-readable text which should be recorded in any telemetry as
  1468.       part of a bug report to the maintainer of the client.
  1469.  
  1470.       In its unsolicited form response indicates some protocol error at
  1471.       the server which cannot be traced to any protocol command.  The
  1472.       text is a line of human-readable text which should be logged in
  1473.       protocol telemetry for the maintainer of the server and/or the
  1474.       client.  This generally indicates a protocol synchronization
  1475.       problem, and examination of the protocol telemetry is advised to
  1476.       determine the cause of the problem.
  1477.  
  1478.    */tag BYE text
  1479.  
  1480.       This indicates that the server is about to close the connection.
  1481.       The text is a line of human-readable text which should be
  1482.       displayed to the user in a status report by the client.  IMAP2
  1483.       requires that the server emit a solicited BYE response as part of
  1484.       a normal logout sequence.  This solicited form is not required
  1485.       under IMAP3, though is still legal for compatibility.  In its
  1486.       unsolicited form the BYE response is used as a panic shutdown
  1487.       announcement by the server.  It is required to be used by any
  1488.       server which performs autologouts due to inactivity.
  1489.  
  1490.    */tag number message_data
  1491.  
  1492.       The solicited (tag number message_data) response is generated as
  1493.       the result of a number of client requests.  The server may also
  1494.       emit any the following at any time as unsolicited data (i.e., *
  1495.       number message_data).  The message_data is one of the following:
  1496.  
  1497.       EXISTS  The specified number of messages exists in the mailbox.
  1498.  
  1499.       RECENT  The specified number of messages have arrived since the
  1500.               last time this mailbox was selected with the SELECT
  1501.               command or equivalent.
  1502.  
  1503.       EXPUNGE The specified message number has been permanently
  1504.               removed from the mailbox, and the next message in the
  1505.               mailbox (if any) becomes that message number.
  1506.              The server must send a solicited EXPUNGE response
  1507.              for each message that it expunges as the result
  1508.              of an EXPUNGE command.  Note: future versions of the
  1509.              protocol may allow the use of a message sequence
  1510.              as a value returned by the EXPUNGE response to allow the
  1511.  
  1512.  
  1513.  
  1514. Rice                                                           [Page 27]
  1515.  
  1516. RFC 1203                         IMAP3                     February 1991
  1517.  
  1518.  
  1519.              more efficient compaction of client representations of
  1520.              mailboxes.
  1521.  
  1522.       STORE data
  1523.              Functionally equivalent to FETCH, only it is sent by the
  1524.              server when the state of a mailbox changes.  The server
  1525.              must send solicited STORE responses as the result of
  1526.              any change caused by a STORE command.
  1527.  
  1528.       FETCH data
  1529.               This is the principle means by which data about a
  1530.               message is sent to the client.  The data is in a
  1531.               Lisp-like S-expression property list form.  Just as the
  1532.               FETCH request from the client can fetch any generic,
  1533.               canonical or concrete key, so also the FETCH response
  1534.               can return values for any of these keys as well as for
  1535.               the pre-defined attributes mentioned below.  Note that
  1536.               the server is permitted to send any unsolicited FETCH
  1537.               or STORE messages that it should choose, be they the
  1538.               values associated with generic, canonical or concrete
  1539.               keys.  Clients are required to ignore any such
  1540.               FETCH responses that it cannot interpret.  For example,
  1541.               clients are not required to be able to understand, i.e.,
  1542.               use fruitfully, the canonical $TO key, but they are
  1543.               required to be able to ignore an unsolicited $TO message
  1544.               correctly.
  1545.  
  1546.          ENVELOPE     An S-expression format list which describes the
  1547.                       envelope of a message.  The envelope is computed
  1548.                       by the server by parsing the RFC 822 header into
  1549.                       the component parts, defaulting various fields
  1550.                       as necessary.
  1551.  
  1552.                       The fields of the envelope are in the following
  1553.                       order: date, subject, from, sender, reply-to, to,
  1554.                       cc, bcc, in-reply-to, and message-id.  The date,
  1555.                       subject, in-reply-to, and message-id fields are
  1556.                       strings.  The from, sender, reply-to, to, cc,
  1557.                       and bcc fields are lists of addresses.
  1558.  
  1559.                       An address is an S-expression format list which
  1560.                       describes an electronic mail address.  The fields
  1561.                       of an address are in the following order:
  1562.                       personal name, source-route (i.e., the
  1563.                       at-domain-list in SMTP), mailbox name, host name
  1564.                       and comments.  Implementation note:  The addition
  1565.                       of the comment field is an incompatible extension
  1566.                       from IMAP2.  The server is required not to provide
  1567.  
  1568.  
  1569.  
  1570. Rice                                                           [Page 28]
  1571.  
  1572. RFC 1203                         IMAP3                     February 1991
  1573.  
  1574.  
  1575.                       this field when running in IMAP2 mode.
  1576.  
  1577.                       Any field of an envelope or address which is
  1578.                       not applicable is presented as the atom NIL.
  1579.                       Note that the server must default the reply-to
  1580.                       and sender fields from the from field; a client is
  1581.                       not expected to know to do this.
  1582.  
  1583.          FLAGS        An S-expression format list of flags which are set
  1584.                       for this message.  This may include the following
  1585.                       system flags:
  1586.  
  1587.                       \RECENT       Message arrived since last
  1588.                                      read of this mailbox
  1589.                       \SEEN         Message has been read
  1590.                       \ANSWERED     Message has been answered
  1591.                       \FLAGGED      Message is "flagged" for
  1592.                                      urgent/special attention
  1593.                       \DELETED      Message is "deleted" for
  1594.                                      removal by later EXPUNGE
  1595.  
  1596.          INTERNALDATE  A string containing the date and time the
  1597.                        message was written to the mailbox.
  1598.  
  1599.          RFC822        A string expressing the message in RFC 822
  1600.                        format.
  1601.                       Note: Some implementations of IMAP2 servers
  1602.                       had the (undocumented) behavior of setting
  1603.                       the \SEEN flag as a side effect of fetching
  1604.                       the body of a message.  This resulted in
  1605.                       erroneous behavior for clients that prefetch
  1606.                       messages that the user might not get
  1607.                       around to reading.  Thus, this behavior is
  1608.                       explicitly disallowed in IMAP3.
  1609.                       Note: this is not a significant performance
  1610.                       restriction because it is always possible for
  1611.                       IMAP3 clients to use an interaction with the
  1612.                       server of the following type:
  1613.                       A001 FETCH 42 RFC822
  1614.                       A002 STORE 42 +FLAGS (\SEEN)
  1615.                       A001 42 FETCH RFC822 {637} ......
  1616.                       A001 OK Fetch completed
  1617.                       A002 42 STORE FLAGS (\SEEN \FLAGGED...)
  1618.                       A002 OK Store Completed.
  1619.  
  1620.          RFC822.HEADER A string expressing the RFC 822 format
  1621.                        header of the message
  1622.  
  1623.  
  1624.  
  1625.  
  1626. Rice                                                           [Page 29]
  1627.  
  1628. RFC 1203                         IMAP3                     February 1991
  1629.  
  1630.  
  1631.          RFC822.SIZE   A number indicating the number of
  1632.                        characters in the message as expressed
  1633.                        in RFC 822 format.
  1634.  
  1635.          RFC822.TEXT   A string expressing the text body of the
  1636.                        message, omitting the RFC 822 header.
  1637.                       See also note for RFC822.
  1638.  
  1639.    */tag FLAGS flag_list
  1640.  
  1641.       A solicited FLAGS response must occur as a result of a SELECT
  1642.       command.  The flag list is the list of flags (at a minimum, the
  1643.       IMAP defined flags) which are applicable for this mailbox.  Flags
  1644.       other than the system flags are a function of the server
  1645.       implementation.
  1646.  
  1647.    */tag SEARCH (numbers) (search_criteria)
  1648.  
  1649.       This response occurs as a result of a SEARCH command.  The
  1650.       number(s) refer to those messages which match the search criteria.
  1651.       In its solicited form this message allows clients to find
  1652.       interesting groups of messages, e.g., unseen messages from
  1653.       Crispin.  In its unsolicited form it allows the server to inform
  1654.       the client of interesting patterns, e.g., when new mail arrives,
  1655.       recent and from Crispin.  Compatibility note:  The search_criteria
  1656.       are sent by the server along with the matching numbers so
  1657.       unsolicited SEARCH messages may be interpreted.  This syntax is
  1658.       not upwards compatible with IMAP2 and so the new syntax is
  1659.       intended to make it simple for clients that are not able to take
  1660.       advantage of unsolicited SEARCH messages still to interpret
  1661.       solicited SEARCH messages simply by ignoring everything that
  1662.       follows the list of numbers with minimal parsing.  Such clients
  1663.       may not, however, simply discard the rest of the line because
  1664.       there might be LITERALs in the search pattern.
  1665.  
  1666.       Examples:
  1667.          A00042 SEARCH (2 3 6) (FROM Crispin ~SEEN)
  1668.       and
  1669.          * SEARCH (42) (FROM Crispin RECENT)
  1670.  
  1671.    */tag READONLY
  1672.  
  1673.       This indicates that the mailbox is read-only.  The server is
  1674.       required to respond to a READONLY or READWRITE command with either
  1675.       a solicited READONLY or a solicited READWRITE response.  Note:  If
  1676.       the client attempts a mutation operation, such as STORE, on a
  1677.       mailbox to which it does not have write access then the server is
  1678.       required to reply with a solicited READONLY response on the first
  1679.  
  1680.  
  1681.  
  1682. Rice                                                           [Page 30]
  1683.  
  1684. RFC 1203                         IMAP3                     February 1991
  1685.  
  1686.  
  1687.       such attempted mutation.  The server may also choose to send
  1688.       solicited READONLY responses for each subsequent attempted
  1689.       mutation.
  1690.  
  1691.    */tag READWRITE
  1692.  
  1693.       This indicates that the mailbox is read-write.  The server is
  1694.       required to respond to a READONLY or READWRITE command with either
  1695.       a solicited READONLY or a solicited READWRITE response.
  1696.  
  1697.    */tag BBOARD bboard_name
  1698.  
  1699.       This message is produced in its solicited form as a response to a
  1700.       FIND BBOARDS command.  In its unsolicited form it represents a
  1701.       notification by the server that a new BBoard has been added.
  1702.       Bboard_name must be a name that can be supplied to the BBOARD
  1703.       command so as to select the appropriate bboard.
  1704.  
  1705.    */tag MAILBOX non_inbox_mailbox_name
  1706.  
  1707.       This message is produced in its solicited form as a response to a
  1708.       FIND MAILBOXES command.  In its unsolicited form it represents a
  1709.       notification by the server that a new mailbox has been added,
  1710.       perhaps as the result of a COPY command creating a new mailbox.
  1711.       Non_inbox_mailbox_name must be a name that can be supplied to the
  1712.       SELECT command so as to select the appropriate mailbox.  Note:
  1713.       non_inbox_mailbox_name is never the string "INBOX".
  1714.  
  1715.    */tag SUPPORTED.VERSIONS (version_specs)
  1716.  
  1717.       This message is used either as a response to the
  1718.       SUPPORTED.VERSIONS or, in its unsolicited form, to indicate the
  1719.       dynamic addition or removal of support for features or protocol
  1720.       versions.  Each version_spec is of the form (4 2
  1721.       EIGHT.BIT.TRANSPARENT AUTO.SET.SEEN ...), i.e., a major version
  1722.       number and a minor version number for the protocol and the set of
  1723.       features supported under the server's implementation of that
  1724.       protocol version.  A server may not dynamically remove support for
  1725.       any version or feature that has been selected by any currently
  1726.       logged in client by the use of the VERSION command.
  1727.  
  1728.       Example:
  1729.         A00005 SUPPORTED.VERSIONS ((2 0 )
  1730.               (2 2 TAGGED.SOLICITED)
  1731.               (3 0 EIGHT.BIT.TRANSPARENT TAGGED.SOLICITED))
  1732.  
  1733.       Indicates that two major versions are supported and one minor
  1734.       version is supported and that tagged solicited messages are
  1735.  
  1736.  
  1737.  
  1738. Rice                                                           [Page 31]
  1739.  
  1740. RFC 1203                         IMAP3                     February 1991
  1741.  
  1742.  
  1743.       supported in versions 2.2 and 3.0 with eight bit characters being
  1744.       supported under version 3.  For each feature mentioned in the list
  1745.       of features there is also always the negation of that feature.
  1746.       For example, if the server supports the TAGGED.SOLICITED feature
  1747.       then it also supports the ~TAGGED.SOLICITED feature, which
  1748.       disables this feature.  Note:  These are only example feature
  1749.       names and are not necessarily supported by any server.  See the
  1750.       appendix on features for more information on features.
  1751.  
  1752.    + text
  1753.  
  1754.       This response indicates that the server is ready to accept the
  1755.       text of a literal from the client.  Normally, a command from the
  1756.       client is a single text line.  If the server detects an error in
  1757.       the command, it can simply discard the remainder of the line.  It
  1758.       cannot do this in the case of commands which contain literals,
  1759.       since a literal can be an arbitrarily long amount of text, and the
  1760.       server may not even be expecting a literal.  This mechanism is
  1761.       provided so the client knows not to send a literal until the
  1762.       server definitely expects it, preserving client/server
  1763.       synchronization.
  1764.  
  1765.       In actual practice, this situation is rarely encountered.  In the
  1766.       current protocol, the only client commands likely to contain
  1767.       literals are the LOGIN command and the STORE RFC822.HEADER or
  1768.       STORE RFC822.TEXT commands.  Consider a situation in which a
  1769.       server validates the user before checking the password.  If the
  1770.       password contains "funny" characters and hence is sent as a
  1771.       literal, then if the user is invalid an error would occur before
  1772.       the password is parsed.
  1773.  
  1774.       No such synchronization protection is provided for literals sent
  1775.       from the server to the client, for performance reasons.  Any
  1776.       synchronization problems in this direction would be due to a bug
  1777.       in the client or server and not for some operational problem.
  1778.  
  1779. Sample IMAP3 session
  1780.  
  1781.    The following is a transcript of an actual IMAP3 session.  Server
  1782.    output is identified by "S:" and client output by "U:".  In cases
  1783.    where lines were too long to fit within the boundaries of this
  1784.    document, the line was continued on the next line preceded by a tab.
  1785.  
  1786.    S:     * OK SUMEX-AIM.Stanford.EDU Interactive Mail Access Protocol
  1787.                   III Service 6.1(349) at Mon, 14 May 90 14:58:30 PDT
  1788.    U:     a001 SUPPORTED.VERSIONS
  1789.    S:     * SUPPORTED.VERSIONS ((2 0 ) (3 0 EIGHT.BIT.TRANSPARENT
  1790.                      AUTO.SET.SEEN TAGGED.SOLICITED))
  1791.  
  1792.  
  1793.  
  1794. Rice                                                           [Page 32]
  1795.  
  1796. RFC 1203                         IMAP3                     February 1991
  1797.  
  1798.  
  1799.    S:     A001 Supported Versions returned.
  1800.    U:     a002 SELECT.VERSION (3 0)
  1801.    S:     a002 OK Version 3.0 Selected.
  1802.    U:     a003 SELECT.FEATURES TAGGED.SOLICITED
  1803.    S:     a003 OK Features selected.
  1804.    U:     a004 login crispin secret
  1805.    S:     a004 OK User CRISPIN logged in at Thu, 9 Jun 90 14:58:42 PDT,
  1806.                   job 76
  1807.    U:     a005 select inbox
  1808.    S:     a005 FLAGS (Bugs SF Party Skating Meeting Flames Request AI
  1809.                   Question Note \XXXX \YYYY \Answered \Flagged \Deleted
  1810.                   \Seen)
  1811.    S:     a005 16 EXISTS
  1812.    S:     a005 0 RECENT
  1813.    S:     a006 OK Select complete
  1814.    U:     a006 fetch 16 all
  1815.    S:     a006 16 Fetch (Flags (\Seen) InternalDate " 9-Jun-88 12:55:
  1816.               RFC822.Size 637 Envelope ("Sat, 4 Jun 88 13:27:11 PDT"
  1817.               "INFO-MAC Mail Message" (("Larry Fagan" NIL "FAGAN"
  1818.               "SUMEX-AIM.Stanford.EDU" NIL)) (("Larry Fagan" NIL "FAGAN"
  1819.               "SUMEX-AIM.Stanford.EDU" NIL)) (("Larry Fagan" NIL "FAGAN"
  1820.               "SUMEX-AIM.Stanford.EDU" NIL)) ((NIL NIL "rindflEISCH"
  1821.               "SUMEX-AIM.Stanford.EDU" NIL)) NIL NIL NIL
  1822.               "<12403828905.13.FAGAN@SUMEX-AIM.Stanford.EDU>"))
  1823.    S:  a006 OK Fetch completed
  1824.    U:  a007 fetch 16 rfc822
  1825.    S:  a007 16 Fetch (RFC822 {637}
  1826.    S:  Mail-From: RINDFLEISCH created at  9-Jun-88 12:55:43
  1827.    S:  Mail-From: FAGAN created at  4-Jun-88 13:27:12
  1828.    S:  Date: Sat, 4 Jun 88 13:27:11 PDT
  1829.    S:  From: Larry Fagan  <FAGAN@SUMEX-AIM.Stanford.EDU>
  1830.    S:  To: rindflEISCH@SUMEX-AIM.Stanford.EDU
  1831.    S:  Subject: INFO-MAC Mail Message
  1832.    S:  Message-ID: <12403828905.13.FAGAN@SUMEX-AIM.Stanford.EDU>
  1833.    S:  ReSent-Date: Thu, 9 Jun 88 12:55:43 PDT
  1834.    S:  ReSent-From: TC Rindfleisch <Rindfleisch@SUMEX-AIM.Stanford.EDU>
  1835.    S:  ReSent-To: Yeager@SUMEX-AIM.Stanford.EDU,
  1836.                   Crispin@SUMEX-AIM.Stanford.EDU
  1837.    S:  ReSent-Message-ID:
  1838.           <12405133897.80.RINDFLEISCH@SUMEX-AIM.Stanford.EDU>
  1839.    S:
  1840.    S:  The file is <info-mac>usenetv4-55.arc  ...
  1841.    S:  Larry
  1842.    S:  -------
  1843.    S:  )
  1844.    S:  a007 OK Fetch completed
  1845.    U:  a008 logout
  1846.    S:  a008 BYE UNIX IMAP III server terminating connection
  1847.  
  1848.  
  1849.  
  1850. Rice                                                           [Page 33]
  1851.  
  1852. RFC 1203                         IMAP3                     February 1991
  1853.  
  1854.  
  1855.    S:  a008 OK SUMEX-AIM.Stanford.EDU Interim Mail Access Protocol
  1856.                   Service logout
  1857.  
  1858. Implementation Discussion
  1859.  
  1860.    As of this writing, SUMEX has completed an IMAP2 client for Xerox
  1861.    Lisp machines written in hybrid Interlisp/CommonLisp and is beginning
  1862.    distribution of a client for TI Explorer Lisp machines.  SUMEX has
  1863.    also completed a portable IMAP2 client protocol library module
  1864.    written in C.  This library, with the addition of a small main
  1865.    program (primarily user interface) and a TCP/IP driver, became a
  1866.    rudimentary remote system mail-reading program under Unix.  The first
  1867.    production use of this library is as a part of a MacII client which
  1868.    has now been under daily use (by real users) at Stanford for quite
  1869.    some time.
  1870.  
  1871.    As of this writing, SUMEX has completed IMAP2 servers for TOPS-20
  1872.    written in DEC-20 assembly language and 4.2/3 BSD Unix written in C.
  1873.    The TOPS-20 server is fully compatible with MM-20, the standard
  1874.    TOPS-20 mailsystem, and requires no special action or setup on the
  1875.    part of the user.  The INBOX under TOPS-20 is the user's MAIL.TXT.
  1876.    The TOPS-20 server also supports multiple simultaneous access to the
  1877.    same mailbox, including simultaneous access between the IMAP3 server
  1878.    and MM-20.  The 4.2/3 BSD Unix server requires that the user use
  1879.    either Unix Mail format or mail.txt format which is compatible with
  1880.    SRI MM-32 or Columbia MM-C.  The 4.2/3 BSD Unix server allows
  1881.    simultaneous read access; write access must be exclusive.  There is
  1882.    also an experimental IMAP3 server running on the TI Explorer class of
  1883.    machine, which uses MM mailbox format and which can communicate over
  1884.    both TCP and Chaos.
  1885.  
  1886.    The Xerox Lisp client and DEC-20 server have been in production use
  1887.    for over two years; the Unix server was been in production use for
  1888.    over a year.  IMAP3 has been used to access mailboxes at remote sites
  1889.    from a local workstation via the Internet.  For example, from the
  1890.    Stanford local network one of the authors has read his mailbox at a
  1891.    Milnet site.
  1892.  
  1893.    A number of IMAP clients have now been developed or are being
  1894.    developed.  Amongst these are versions that run on the following
  1895.    machines:
  1896.  
  1897.     . Xerox Lisp machines
  1898.     . Apple Macintosh
  1899.     . NeXT
  1900.     . IBM PC
  1901.     . TI Explorer Lisp machines
  1902.     . "Glass teletype" version that runs under Unix
  1903.  
  1904.  
  1905.  
  1906. Rice                                                           [Page 34]
  1907.  
  1908. RFC 1203                         IMAP3                     February 1991
  1909.  
  1910.  
  1911.     . GNU Emacs
  1912.     . X Windows
  1913.     . NTT ELIS
  1914.  
  1915.    Each of these client programs is carefully tuned to optimize the
  1916.    performance and user interface in a manner that is consistent with
  1917.    the the user interface model of the native machine.  For example, the
  1918.    Macintosh client features a "messy-desk" interface that allows the
  1919.    cutting and pasting of text with the use of the clipboard with a menu
  1920.    driven interface with keyboard accelerators.
  1921.  
  1922.    This specification does not make any formal definition of size
  1923.    restrictions, but some of the existing servers have the following
  1924.    limitations:
  1925.  
  1926.    DEC-20
  1927.     . length of a mailbox: 7,077,888 characters
  1928.     . maximum number of messages: 18,432 messages
  1929.     . length of a command line: 10,000 characters
  1930.     . length of the local host name: 64 characters
  1931.     . length of a "short" argument: 39 characters
  1932.     . length of a "long" argument: 491,520 characters
  1933.     . maximum amount of data output in a single fetch:
  1934.       655,360 characters
  1935.  
  1936.    TI-Explorer
  1937.     . length of a mailbox: limited by the Minimum of the size of the
  1938.       virtual address space and the size of the file system
  1939.     . maximum number of messages: limited by the the size of the
  1940.       virtual address space
  1941.     . length of a command line: limited by the the size of the
  1942.       virtual address space
  1943.     . length of the local host name: limited by the the size of the
  1944.       virtual address space
  1945.     . length of a "short" argument: limited by the the size of the
  1946.       virtual address space
  1947.     . length of a "long" argument: limited by the the size of the
  1948.       virtual address space
  1949.     . maximum amount of data output in a single fetch: not limited
  1950.  
  1951.    Typical values for these limits are 30Mb for file systems and 128Mb
  1952.    for virtual address space.
  1953.  
  1954.    To date, nobody has run up against any of these limitations, many of
  1955.    which are substantially larger than most current user mail reading
  1956.    programs.
  1957.  
  1958.    There are several advantages to the scheme of tags and solicited
  1959.  
  1960.  
  1961.  
  1962. Rice                                                           [Page 35]
  1963.  
  1964. RFC 1203                         IMAP3                     February 1991
  1965.  
  1966.  
  1967.    responses and unsolicited data.  First, the infamous synchronization
  1968.    problems of SMTP and similar protocols do not happen with tagged
  1969.    commands; a command is not considered satisfied until a completion
  1970.    acknowledgement with the same tag is seen.  Tagging allows an
  1971.    arbitrary amount of other responses ("solicited" data) to be sent by
  1972.    the server with no possibility of the client losing synchronization.
  1973.    Compare this with the problems that FTP or SMTP clients have with
  1974.    continuation, partial completion, and commentary reply codes.
  1975.  
  1976.    Another advantage is that a non-lockstep client implementation is
  1977.    possible.  The client could send a command, and entrust the handling
  1978.    of the server responses to a different process which would signal the
  1979.    client when the tagged response comes in.  Some clients might be
  1980.    implemented in a thoroughly asynchronous manner, having, perhaps,
  1981.    multiple outstanding commands at any given time.  Note:  this does
  1982.    not require that the server process these commands in anything other
  1983.    than a lock-step manner.  It simply allows clients to take advantage
  1984.    of servers that are able to do such asynchronous operations.
  1985.  
  1986.    It was observed that synchronization problems can occur with literals
  1987.    if the literal is not recognized as such.  Fortunately, the cases in
  1988.    which this can happen are relatively rare; a mechanism (the special
  1989.    "+" tag response) was introduced to handle those few cases which
  1990.    could happen.  The proper way to address this problem in all cases is
  1991.    probably to move towards a record-oriented architecture instead of
  1992.    the text stream model provided by TCP.
  1993.  
  1994.    Unsolicited data needs some discussion.  Unlike most protocols, in
  1995.    which the server merely does the client's bidding, an IMAP3 server
  1996.    has a semi-autonomous role.  By means of sending "unsolicited data",
  1997.    the server is in effect sending a command to the client -- to update
  1998.    and/or extend its (incomplete) model of the mailbox with new
  1999.    information from the server.  In this viewpoint, although a "fetch"
  2000.    command is a request for specific information from the client, the
  2001.    server is always at liberty to include more than the desired data as
  2002.    "unsolicited".  A server acknowledgement to the "fetch" is a
  2003.    statement that at least all the requested data has been sent.
  2004.  
  2005.    In terms of implementation, a simple lock-step client may have a
  2006.    local cache of data from the mailbox.  This cache is incomplete in
  2007.    general, and at select time is empty.  A listener on the IMAP
  2008.    connection in the client processes all solicited and unsolicited data
  2009.    symmetrically, and updates the cache based on this data, i.e., the
  2010.    client faults on a cache miss and asks the server to fill that cache
  2011.    slot synchronously.  If a tagged completion response arrives, the
  2012.    listener unblocks the process which sent the tagged request.
  2013.  
  2014.    Clearly, given this model it is not strictly necessary to distinguish
  2015.  
  2016.  
  2017.  
  2018. Rice                                                           [Page 36]
  2019.  
  2020. RFC 1203                         IMAP3                     February 1991
  2021.  
  2022.  
  2023.    most solicited from unsolicited data.  Doing so, however, apart from
  2024.    being clearer, also allows such simplistic, lock-step client
  2025.    implementations that extract the specific value of the response to
  2026.    command by trapping the tagged response.  This allows the client not
  2027.    to have to block on some complex predicate that involves watching to
  2028.    see an update in a cache cell.
  2029.  
  2030.    For example, perhaps as a result of opening a mailbox, solicited data
  2031.    from the server arrives.  The first piece of data is the number of
  2032.    messages.  This is used to size the cache; note that, if new mail
  2033.    arrives, by sending a new "number of messages" unsolicited data
  2034.    message server will cause the cache to be re-sized.  If the client
  2035.    attempts to access information from the cache, it will encounter
  2036.    empty spots which will trigger "fetch" requests.  The request would
  2037.    be sent, some solicited data including the answer to the fetch will
  2038.    flow back, and then the "fetch" response will unblock the client.
  2039.  
  2040.    People familiar with demand-paged virtual memory design will
  2041.    recognize this model as being very similar to page-fault handling on
  2042.    a demand-paged system.
  2043.  
  2044. Formal Syntax
  2045.  
  2046.    The following syntax specification uses the augmented Backus-Naur
  2047.    Form (BNF) notation as specified in RFC 822 with one exception; the
  2048.    delimiter used with the "#" construct is a single space (SP) and not
  2049.    a comma.
  2050.  
  2051. address         ::= "(" addr_name SP addr_adl SP addr_mailbox SP
  2052.                     addr_host addr_comment ")"
  2053.  
  2054. addr_adl        ::= nil / string
  2055.  
  2056. addr_comment    ::= nil / string
  2057.  
  2058. addr_host       ::= nil / string
  2059.  
  2060. addr_mailbox    ::= nil / string
  2061.  
  2062. addr_name       ::= nil / string
  2063.  
  2064. bboard          ::= "BBOARD" SP bboard_name
  2065.  
  2066. bboard_name     ::= string
  2067.  
  2068. bboard_notify   ::= "BBOARD" sp bboard_name
  2069.  
  2070. canonical_key   ::= "$CC" /  "$FROM" / "$SUBJECT" / "$TO"
  2071.  
  2072.  
  2073.  
  2074. Rice                                                           [Page 37]
  2075.  
  2076. RFC 1203                         IMAP3                     February 1991
  2077.  
  2078.  
  2079. check           ::= "CHECK"
  2080.  
  2081. concrete_key    ::= string
  2082.  
  2083. copy            ::= "COPY" SP sequence SP mailbox
  2084.  
  2085. criterion       ::= "ALL" / "ANSWERED" /
  2086.                     "BCC" SP string / "BEFORE" SP string /
  2087.                     "BODY" SP string / "CC" SP string / "DELETED" /
  2088.                     "FLAGGED" / "KEYWORD" SP atom / "NEW" / "OLD" /
  2089.                     "ON" SP string / "RECENT" / "SEEN" /
  2090.                     "SINCE" SP string / "TEXT" SP string /
  2091.                     "TO" SP string / "UNANSWERED" / "UNDELETED" /
  2092.                     "UNFLAGGED" / "UNKEYWORD" / "UNSEEN" / key SP string
  2093.  
  2094. criteria        ::= 1#criterion
  2095.  
  2096. data            ::= ("FLAGS" SP flag_list /
  2097.                   search_notify / bboard_notify / mailbox_notify /
  2098.                   supported_versions_notify / "READONLY" / "READWRITE" /
  2099.                     "BYE" SP text_line / "OK" SP text_line /
  2100.                     "NO" SP text_line / "BAD" SP text_line)
  2101.  
  2102. date            ::= string in form "dd-mmm-yy hh:mm:ss-zzz"
  2103.  
  2104. envelope        ::= "(" env_date SP env_subject SP env_from SP
  2105.                     env_sender SP env_reply-to SP env_to SP
  2106.                     env_cc SP env_bcc SP env_in-reply-to SP
  2107.                     env_message-id ")"
  2108.  
  2109. env_bcc         ::= nil / "(" 1*address ")"
  2110.  
  2111. env_cc          ::= nil / "(" 1*address ")"
  2112.  
  2113. env_date        ::= string
  2114.  
  2115. env_from        ::= nil / "(" 1*address ")"
  2116.  
  2117. env_in-reply-to ::= nil / string
  2118.  
  2119. env_length      ::= NUMBER
  2120.  
  2121. env_message-id  ::= nil / string
  2122.  
  2123. env_reply-to    ::= nil / "(" 1*address ")"
  2124.  
  2125. env_sender      ::= nil / "(" 1*address ")"
  2126.  
  2127.  
  2128.  
  2129.  
  2130. Rice                                                           [Page 38]
  2131.  
  2132. RFC 1203                         IMAP3                     February 1991
  2133.  
  2134.  
  2135. env_subject     ::= nil / string
  2136.  
  2137. env_to          ::= nil / "(" 1*address ")"
  2138.  
  2139. expunge         ::= "EXPUNGE"
  2140.  
  2141. feature         ::= ATOM
  2142.  
  2143. fetch           ::= "FETCH" SP sequence SP ("ALL" / "FAST" /
  2144.                     fetch_att / "(" 1#fetch_att ")")
  2145.  
  2146. fetch_att       ::= "ENVELOPE" / "FLAGS" / "INTERNALDATE" /
  2147.                     "RFC822" / "RFC822.HEADER" / "RFC822.SIZE" /
  2148.                     "RFC822.TEXT" / key
  2149.  
  2150. find            ::= "FIND" ("BBOARDS" / "MAILBOXES") pattern
  2151.  
  2152. flag_list       ::= ATOM / "(" 1#ATOM ")"
  2153.  
  2154. flags           ::= "FLAGS"
  2155.  
  2156. generic_key     ::= "BCC" / "BODY" / "CC" / "FROM" / "HEADER" / "SIZE" /
  2157.                     "SUBJECT" / "TEXT" / "TO"
  2158.  
  2159. key             ::= generic_key / canonical_key / concrete_key
  2160.  
  2161. literal         ::= "{" NUMBER "}" CRLF ASCII-STRING
  2162.  
  2163. login           ::= "LOGIN" SP userid SP password
  2164.  
  2165. logout          ::= "LOGOUT"
  2166.  
  2167. mailbox         ::= "INBOX" / string
  2168.  
  2169. mailbox_notify ::= MAILBOX non_inbox_mailbox_name
  2170.  
  2171. msg_copy        ::= "COPY"
  2172.  
  2173. msg_data        ::= (msg_exists / msg_recent / msg_expunge /
  2174.                     msg_fetch / msg_copy)
  2175.  
  2176. msg_exists      ::= "EXISTS"
  2177.  
  2178. msg_expunge     ::= "EXPUNGE"
  2179.  
  2180. msg_fetch       ::= ("FETCH" / "STORE") SP "(" 1#("ENVELOPE" SP
  2181.                      env_length envelope / "FLAGS" SP "(" 1#(recent_flag
  2182.                      flag_list) ")" / "INTERNALDATE" SP date /
  2183.  
  2184.  
  2185.  
  2186. Rice                                                           [Page 39]
  2187.  
  2188. RFC 1203                         IMAP3                     February 1991
  2189.  
  2190.  
  2191.                      "RFC822" SP string / "RFC822.HEADER" SP string /
  2192.                      "RFC822.SIZE" SP NUMBER / "RFC822.TEXT" SP
  2193.                      string / key SP string_list) ")"
  2194.  
  2195. msg_recent      ::= "RECENT"
  2196.  
  2197. msg_num         ::= NUMBER
  2198.  
  2199. nil             ::= "NIL"
  2200.  
  2201. non_inbox_mailbox_name ::= string
  2202.  
  2203. noop            ::= "NOOP"
  2204.  
  2205. numbers         ::= 1#NUMBER
  2206.  
  2207. password        ::= string
  2208.  
  2209. pattern         ::= string
  2210.  
  2211. recent_flag     ::= "\RECENT"
  2212.  
  2213. read_only       ::= "READONLY"
  2214.  
  2215. read_write      ::= "READWRITE"
  2216.  
  2217. ready           ::= "+" SP text_line
  2218.  
  2219. request         ::= tag SP (noop / login / logout / select / check /
  2220.                     expunge / copy / fetch / store / search /
  2221.                     select_version / select_features /
  2222.                     supported_versions / bboard / find /
  2223.                     read_only / read_write / flags / set_flags ) CRLF
  2224.  
  2225. response        ::= tag SP ("OK" / "NO" / "BAD") SP text_line CRLF
  2226.  
  2227. search          ::= "SEARCH" SP criteria
  2228.  
  2229. search_notify   ::= "SEARCH" SP (numbers) SP (criteria)
  2230.  
  2231. select          ::= "SELECT" SP mailbox
  2232.  
  2233. select_features ::= "SELECT.FEATURES" 1#feature
  2234.  
  2235. select_version  ::= "SELECT.VERSION" SP "(" NUMBER SP NUMBER ")"
  2236.  
  2237. sequence        ::= NUMBER / (NUMBER "," sequence) / (NUMBER ":"
  2238.                     sequence)
  2239.  
  2240.  
  2241.  
  2242. Rice                                                           [Page 40]
  2243.  
  2244. RFC 1203                         IMAP3                     February 1991
  2245.  
  2246.  
  2247. set_flags       ::= "SET.FLAGS" SP flag_list
  2248.  
  2249. solicited       ::= tag SP (msg_num SP msg_data / data /
  2250.                             solicited_only) CRLF
  2251.  
  2252. solicited_only  ::=                {None currently defined}
  2253.  
  2254. store           ::= "STORE" SP sequence SP store_att
  2255.  
  2256. store_att       ::= ("+FLAGS" SP flag_list / "-FLAGS" SP flag_list /
  2257.                     "FLAGS" SP flag_list / RFC822.TEXT SP string
  2258.                     / RFC822.HEADER SP string / key SP string)
  2259.  
  2260. string          ::= atom / """" 1*character """" / literal
  2261.  
  2262. string_list     ::= string / ("(" 1#string ")")
  2263.  
  2264. supported_versions ::= "SUPPORTED.VERSIONS"
  2265.  
  2266. supported_versions_notify ::= "SUPPORTED.VERSIONS" "(" 1#version_spec
  2267.                               ")"
  2268.  
  2269. system_flags    ::= "\ANSWERED" SP "\FLAGGED" SP "\DELETED" SP
  2270.                     "\SEEN"
  2271.  
  2272. tag             ::= atom
  2273.  
  2274. unsolicited     ::= "*" SP (msg_num SP msg_data / data) CRLF
  2275.  
  2276. userid          ::= string
  2277.  
  2278. version_spec    ::= "(" NUMBER SP NUMBER SP 1#feature ")"
  2279.  
  2280. Appendix: Features.
  2281.  
  2282.    In this section we outline the standard features that are supported
  2283.    by all IMAP3 servers and identify those features which are
  2284.    recommended or experimental.  For each of these features the default
  2285.    setting is specified.  This means that it is required of any server
  2286.    that supports a given feature to make the default enabledness of that
  2287.    feature as is specified below.  It is required that for each feature
  2288.    supported by a server the inverse feature should also be supported.
  2289.    The inverse feature name shall always be defined as the feature name
  2290.    preceded by the "~" character.  Thus, the AUTO.SET.SEEN feature is
  2291.    disabled by the ~AUTO.SET.SEEN feature.
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298. Rice                                                           [Page 41]
  2299.  
  2300. RFC 1203                         IMAP3                     February 1991
  2301.  
  2302.  
  2303.    Required Features:
  2304.  
  2305.    AUTO.SET.SEEN - When this features is enabled (default is disabled),
  2306.         the \\SEEN flag is set for all appropriate messages as a side
  2307.         effect of any of the following:
  2308.             FETCH of RFC822
  2309.             FETCH of RFC822.TEXT
  2310.             COPY
  2311.         Justification:  This feature is provided for the use of clients
  2312.         that are unable to pipeline their commands effectively and
  2313.         communicate over high latency connections.  When disabled,
  2314.         the server will not perform any such side effects.  This feature
  2315.         is also provided so as to smooth the transition from IMAP2 to
  2316.         IMAP3.
  2317.  
  2318.  
  2319.    TAGGED.SOLICITED - When this feature is enabled (default is enabled
  2320.         for IMAP3, disabled for IMAP2 mode), solicited responses from
  2321.         the server will have the tag specified by the client.
  2322.         When this feature is disabled, solicited responses from the
  2323.         server will have the IMAP2 compatible tag "*", not the
  2324.         tag specified by the client.
  2325.         Justification:  This feature is provided so as to smooth the
  2326.         transition from IMAP2 to IMAP3.
  2327.  
  2328.    Recommended Features.
  2329.  
  2330.    EIGHT.BIT.TRANSPARENT - When this feature is enabled
  2331.         (default is disabled), the server allows the transparent
  2332.         transmission of eight bit characters.  When this feature is
  2333.         disabled, the value of any bit other than the least significant
  2334.         7 bits transmitted by the server is unspecified.  If this
  2335.         feature is enabled, the characters that compose all command
  2336.         keywords specified in the IMAP3 grammar and all feature names
  2337.         use only their 7 least significant bits.
  2338.         Justification:  This feature is provided for the purpose of
  2339.         supporting national character sets within messages, encoded
  2340.         languages such as Japanese Kanji characters and also of binary
  2341.         data, such as programs, graphics and sound.
  2342.  
  2343.  
  2344.    NEW.MAIL.NOTIFY - When this feature is enabled (default is
  2345.         disabled for compatibility with the majority of existing
  2346.         IMAP2 servers), the server will notify the client of the
  2347.         arrival of new mail in the currently selected mailbox
  2348.         using the appropriate RECENT and EXISTS unsolicited messages
  2349.         without the client needing to send periodic CHECK commands.
  2350.         Justification:  This feature is provided to allow clients to
  2351.  
  2352.  
  2353.  
  2354. Rice                                                           [Page 42]
  2355.  
  2356. RFC 1203                         IMAP3                     February 1991
  2357.  
  2358.  
  2359.         switch off any periodic polling strategy that they may use
  2360.         to look for new mail.  Such polling unnecessarily uses bandwidth
  2361.         and can cause the interactive performance to degrade because
  2362.         the user can be kept waiting while some background process
  2363.         is doing a CHECK.
  2364.  
  2365.  
  2366.    SEND - When this feature is enabled (default is disabled) a new
  2367.         "SEND" command becomes available to the client.  The SEND
  2368.         command instructs the server to send a message, rather
  2369.         than requiring the client to use its own, local message
  2370.         sending capability, for example.  An example of of the
  2371.         send command might be as follows:
  2372.             tag42 SEND RFC822 {2083}
  2373.             From: James Rice <Rice@Sumex-Aim.Stanford.Edu>
  2374.             To:.....
  2375.         If the server is unable to parse the message being sent then
  2376.         it is required to issue a suitable NO notification to the client.
  2377.         If the message cannot be delivered for some reason then the
  2378.         server should send a suitable message to the FROM: address
  2379.         of the message detailing the delivery failure.
  2380.         When the SEND feature is enabled, the "send" production in
  2381.         the grammar is added and as defined below.  The "send"
  2382.         request is added to the list of requests in the request
  2383.         production also as shown below:
  2384.  
  2385.    message_format  ::= RFC822
  2386.  
  2387.    request         ::= tag SP (noop / login / logout / select / check /
  2388.                        expunge / copy / fetch / store / search /
  2389.                        select_version / select_features /
  2390.                        supported_versions / bboard / find /
  2391.                        read_only / read_write / flags /
  2392.                        set_flags / send) CRLF
  2393.  
  2394.    send            ::= SEND SP message_format SP string
  2395.  
  2396.         Justification:  This feature is provided so that mail can be
  2397.         sent by the same reliable server that is used for the storage
  2398.         of mail.  This has, amongst others, the following benefits:
  2399.         - Single process clients need not be delayed by mail
  2400.           transmission.
  2401.         - Mail sent by the client will have the server named as the
  2402.           message's sender.  This can be important because there are
  2403.           a lot of mailers that erroneously cause reply mail to be
  2404.           sent to the Sender, not the From or Reply-To address.  Since
  2405.           the client in general is not listening for mail being sent
  2406.           to it directly this can cause mail to be lost.
  2407.  
  2408.  
  2409.  
  2410. Rice                                                           [Page 43]
  2411.  
  2412. RFC 1203                         IMAP3                     February 1991
  2413.  
  2414.  
  2415.         - Clients can be written that do not have any native message
  2416.           sending capability.
  2417.  
  2418.  
  2419.    ADD.MESSAGE - When this feature is enabled (default is disabled)
  2420.         a new "ADD.MESSAGE" command becomes available to the client.
  2421.         The ADD.MESSAGE command instructs the server to add the
  2422.         specified message to the designated mailbox.  This command
  2423.         can be thought of as being like a COPY command except in
  2424.         this case the message that is put in the designated mailbox
  2425.         is specified as a string, rather than as a message number to
  2426.         be copied from the currently selected mailbox.  An example
  2427.         use of this command might be as follows:
  2428.             tag42 ADD.MESSAGE OUTGOING-MAIL RFC822 {2083}
  2429.             From: James Rice <Rice@Sumex-Aim.Stanford.Edu>
  2430.             To:.....
  2431.         This will have the effect of adding the message to the mailbox
  2432.         called OUTGOING-MAIL.
  2433.         If the server is unable to parse the message being added then
  2434.         it is required to issue a suitable NO notification to the client.
  2435.         When the ADD.MESSAGE feature is enabled, the "add_message"
  2436.         production in the grammar is added and as defined below.
  2437.         The "add_message" request is added to the list of requests
  2438.         in the request production also as shown below:
  2439.  
  2440.    add_message            ::= ADD.MESSAGE SP mailbox SP format SP string
  2441.  
  2442.    message_format  ::= RFC822
  2443.  
  2444.    request         ::= tag SP (noop / login / logout / select / check /
  2445.                        expunge / copy / fetch / store / search /
  2446.                        select_version / select_features /
  2447.                        supported_versions / bboard / find /
  2448.                        read_only / read_write / flags / set_flags /
  2449.                        add_message) CRLF
  2450.  
  2451.         Justification:  This feature is provided so that clients can
  2452.         easily add mail to specific mailboxes.  This allows clients
  2453.         to implement such behavior as outgoing mail storage (BCC)
  2454.         without the need to resort to mailing to special BCC mailboxes.
  2455.  
  2456.  
  2457.    RENUMBER - When this feature is enabled (default is disabled)
  2458.         the RENUMBER command becomes available to the client.
  2459.         The RENUMBER command will reorder the assignment of message
  2460.         numbers to the messages in the mailbox.  If this results in a
  2461.         change to the association of any message number with any
  2462.         message then the server is required to send solicited RESET
  2463.  
  2464.  
  2465.  
  2466. Rice                                                           [Page 44]
  2467.  
  2468. RFC 1203                         IMAP3                     February 1991
  2469.  
  2470.  
  2471.         responses to the client.  The intent of this command is
  2472.         to allow users to view mailboxes in user-meaningful order
  2473.         efficiently.  While the client could do the ordering,
  2474.         it would be less efficient in general.  Note that the
  2475.         server may or may not change the actual storage of the
  2476.         messages and the ordering may or may not remain in effect
  2477.         after another mailbox is selected or the IMAP session is
  2478.         terminated.  Informally, the syntax for the RENUMBER
  2479.         command is:
  2480.  
  2481.             tag RENUMBER field_name ordering_type
  2482.  
  2483.         this has the effect of changing the IMAP grammar to be
  2484.         as follows:
  2485.  
  2486.    ordering_type   ::= DATE / NUMERIC / ALPHA
  2487.  
  2488.    renumber        ::= RENUMBER SP field_name SP ordering_type
  2489.  
  2490.    request         ::= tag SP (noop / login / logout / select / check /
  2491.                        expunge / copy / fetch / store / search /
  2492.                        select_version / select_features /
  2493.                        supported_versions / bboard / find /
  2494.                        read_only / read_write / flags / set_flags /
  2495.                        renumber) CRLF
  2496.  
  2497.         For example:
  2498.          tag42 RENUMBER FROM ALPHA
  2499.                          ;;;RENUMBER alphabetically by the from field
  2500.          tag42 RESET 10:20,49
  2501.                          ;;;Messages 10 to 20 and 49 have changed
  2502.          tag42 OK RENUMBER finished.  Sequence has changed
  2503.          tag43 FETCH ALL 10:20,49
  2504.                          ;;;Client chooses to fetch the changed msgs.
  2505.  
  2506.         To support this the RESET message is defined as follows:
  2507.  
  2508.    */tag RESET message_sequence
  2509.        This solicited of unsolicited message from the server informs the
  2510.        client that it should flush any information that it has
  2511.        retained for the specified messages.
  2512.  
  2513.         Justification:  This feature is provided so that clients can
  2514.         view mailboxes in an order that is convenient to the user.
  2515.         This is particularly important in the context of mailboxes
  2516.         that the user copies messages to from other mailboxes.  This
  2517.         user-controlled filing process often does not happen in any
  2518.         well-defined order.  Because messages in a mailbox are
  2519.  
  2520.  
  2521.  
  2522. Rice                                                           [Page 45]
  2523.  
  2524. RFC 1203                         IMAP3                     February 1991
  2525.  
  2526.  
  2527.         implicitly ordered (usually by arrival date, though this is
  2528.         not a required ordering predicate), the user can be confused
  2529.         by the apparent order of messages in the mailbox.  The
  2530.         addition of the RENUMBER command makes it unnecessary
  2531.         for the user to leave IMAP and use some other mail system to
  2532.         sort mailboxes.
  2533.  
  2534.  
  2535.    ENCODING - When this feature is enabled (default is disabled) a new
  2536.         generic key named ENCODING is defined.  The value associated
  2537.         with the generic ENCODING key is a list of (tag encoding-type
  2538.         options...) lists that represent the ordered, possibly encoded
  2539.         body of the message.  Each such list represents a segment of
  2540.         the body of the message and the way in which it is encoded.
  2541.         Any options that follow the encoding_type are further
  2542.         qualifiers that describe the format of the segment.  Each tag
  2543.         is created by the server and is unique with respect to the
  2544.         other tags allocated for the other elements in the ENCODING
  2545.         list.  The client may use the tags returned by the server as
  2546.         concrete keys to access a field which is encoded using the
  2547.         encoding type and options mentioned in the appropriate list.
  2548.         Thus:
  2549.  
  2550.  tag41 FETCH 196 ENCODING ; Client asks for encoding field of msg 196.
  2551.  tag41 FETCH ENCODING NIL ; Server replies. This message is not encoded.
  2552.  tag41 OK Fetch completed.
  2553.  tag42 FETCH 197 ENCODING ; Client asks for encoding field of msg 197.
  2554.  tag42 FETCH ENCODING ((G001 UUENCODE) (G002 HEX)) ; Server replies.
  2555.  tag42 OK Fetch completed.
  2556.  tag43 FETCH 197 G002     ; Client asks for field named G002
  2557.  tag43 FETCH G002 "A0 00 FF 13 42......." ; Server sends value of field.
  2558.  tag43 OK Fetch completed.
  2559.  
  2560.      or
  2561.  
  2562.  tag44 STORE 197 G002 "0A 00 FF 31 24......."
  2563.     ; Store back the segment with nibbles swapped
  2564.  
  2565.       Note:  As a side-effect of enabling this feature, the generic key
  2566.       TEXT will be redefined so as to return only those body parts of a
  2567.       message that are of type TEXT.  The concrete key RFC822.TEXT, on
  2568.       the other hand, would still return everything in the body of the
  2569.       message, even if it was full of strange, binary character
  2570.       sequences.
  2571.  
  2572.       When the client STOREs to a field denoted by one of the above tags
  2573.       the server will interpret the value being passed as being in the
  2574.       same format as is currently specified in the ENCODING field.  The
  2575.  
  2576.  
  2577.  
  2578. Rice                                                           [Page 46]
  2579.  
  2580. RFC 1203                         IMAP3                     February 1991
  2581.  
  2582.  
  2583.       server is not required to be able to reformat the data associated
  2584.       with the ENCODING tags if the client STOREs a new value for the
  2585.       ENCODING field.  The interpretability of a message in the context
  2586.       of its ENCODING field is undefined if the client side-effects that
  2587.       ENCODING field, unless the client also STOREs new, reformatted
  2588.       values for the fields that have had their encoding changed.
  2589.  
  2590.       If the client stores a new value for the ENCODING field then the
  2591.       tags in the new value will be used to index the parts of the body.
  2592.       All tags in a client-STOREd ENCODING that are the same as those
  2593.       originally generated by the server in response to a FETCH ENCODING
  2594.       command are said still to denote the fields that they originally
  2595.       denoted, though possibly reordered.  Any tags not originally
  2596.       defined by the server will denote new message parts, in the
  2597.       appropriate format, in the relative position specified.  The
  2598.       exclusion of any tags that the server originally defined in a
  2599.       FETCH of the ENCODING field will indicate the deletion of that
  2600.       part of the message.  Newly created message parts are undefined by
  2601.       default, so if the client fails to follow the STOREing of the
  2602.       ENCODING field with suitable STORE commands for the values
  2603.       associated with any newly created tags, these fields will contain
  2604.       the null value NIL.
  2605.  
  2606.       Justification:  This feature is supplied so as to allow support
  2607.       for emergent multi-part and multi-media mail standards.
  2608.  
  2609.    INDEXABLE.FIELDS - When this feature is enabled (default is
  2610.         disabled) the grammar of fetch commands is changed to allow the
  2611.         client to select a specific subsequence from the field in
  2612.         question.  For example:
  2613.  
  2614.           tag42 FETCH 197 BODY 2000:3999
  2615.  
  2616.         would fetch the second two thousand bytes of the body of message
  2617.         197.  This feature allows resource limited clients to access
  2618.         small parts of large messages.  The formal syntax for this is:
  2619.  
  2620.    fetch_att       ::= "ENVELOPE" / "FLAGS" / "INTERNALDATE" /
  2621.                        fetch_key / (fetch_key SP NUMBER ":" NUMBER)
  2622.  
  2623.    fetch_key       ::= "RFC822" / "RFC822.HEADER" / "RFC822.SIZE" /
  2624.                        "RFC822.TEXT" / key
  2625.  
  2626.       If the lower bound number (the number to the left of the colon)
  2627.       exceeds the maximum size of the field then the empty string is
  2628.       returned.  If the upper bound exceeds the maximum size of the
  2629.       field but the lower bound does not then the server will return the
  2630.       remaining substring of the field after the lower bound.  The
  2631.  
  2632.  
  2633.  
  2634. Rice                                                           [Page 47]
  2635.  
  2636. RFC 1203                         IMAP3                     February 1991
  2637.  
  2638.  
  2639.       bounds specified are zero indexed into the fields and the bounds
  2640.       index fields by 8-bit bytes.
  2641.  
  2642.       Justification:  This feature is provided so as to allow resource-
  2643.       limited clients to read very large messages and also to allow
  2644.       clients to improve interactive response for the reading of large
  2645.       messages by fetching the first "screen full" of data to display
  2646.       immediately and fetching the rest of the message in the
  2647.       background.
  2648.  
  2649.    SET.EOL - When enabled (default is disabled), this feature
  2650.         allows the new command SET.EOL to be available, changing the
  2651.         grammar as follows:
  2652.  
  2653.    character       ::= "CR" / "LF" / number
  2654.  
  2655.    request         ::= tag SP (noop / login / logout / select / check /
  2656.                        expunge / copy / fetch / store / search /
  2657.                        select_version / select_features /
  2658.                        supported_versions / bboard / find /
  2659.                        read_only / read_write / flags / set_flags /
  2660.                        set_eol) CRLF
  2661.  
  2662.    set_eol         ::= "SET.EOL" 1#character
  2663.  
  2664.       This has the effect of changing the end of line character sequence
  2665.       generated by the server for newlines within strings to the
  2666.       sequence of characters specified.  The characters in the sequence
  2667.       can be either the specified symbolically named characters or a
  2668.       numerical value, specifying the decimal value of the character to
  2669.       use.  Thus, if the client would like newlines in strings to be
  2670.       indicated by a carriage return followed by a control-d, the client
  2671.       would issue the following command:
  2672.  
  2673.            tag42 SET.EOL CR 4
  2674.  
  2675.       If the server is unable to support the combination of characters
  2676.       requested by the client as its end-of-line pattern it will reply
  2677.       with a NO response.  This might be the case, for example, if a
  2678.       server is only able to generate its own native line feed pattern
  2679.       and the CRLF required by IMAP by default.
  2680.  
  2681.       The server is required to change any length denoting values, such
  2682.       as envelope byte counts for all future transactions to reflect the
  2683.       new eol setting.  This change in reported sizes should apply to
  2684.       all generic size fetching keys, but not to concrete ones such as
  2685.       RFC822.SIZE, which by their very nature require a size measurement
  2686.       in RFC822 format, i.e., with CRLF as the end-of-line convention.
  2687.  
  2688.  
  2689.  
  2690. Rice                                                           [Page 48]
  2691.  
  2692. RFC 1203                         IMAP3                     February 1991
  2693.  
  2694.  
  2695.       Justification: This feature is provided because frequently clients
  2696.       and servers might have end-of-line conventions other than the CRLF
  2697.       specified by RFC822.  It is undesirable that the IMAP be linked
  2698.       too closely to RFC822 and selecting a different convention might
  2699.       allow substantial performance improvements in both clients and
  2700.       servers by saving either client, server or both from having to
  2701.       shuffle text around so as to add or remove non-local end-of-line
  2702.       sequences.
  2703.  
  2704. Acknowledgements:
  2705.  
  2706.    This text is based on RFC 1064 by Mark Crispin.
  2707.  
  2708.    The following have made major contributions to this proposed update
  2709.    to the IMAP2 protocol:
  2710.  
  2711.       James Rice               <Rice@sumex-aim.stanford.edu>
  2712.       Richard Acuff            <acuff@sumex-aim.stanford.edu>
  2713.       Bill Yeager              <yeager@sumex-aim.stanford.edu>
  2714.       Christopher Lane         <lane@sumex-aim.stanford.edu>
  2715.       Bjorn Victor             <Bjorn.Victor@docs.uu.se>
  2716.  
  2717.    Additional input was also received from:
  2718.  
  2719.       Andrew Sweer             <sweer@sumex-aim.stanford.edu>
  2720.       Tom Gruber               <Gruber@sumex-aim.stanford.edu>
  2721.       Kevin Brock              <Brock@Sumex-Aim.Stanford.Edu>
  2722.       Mark Crispin             <MRC@cac.washington.edu>
  2723.  
  2724. Security Considerations
  2725.  
  2726.    Security issues are not discussed in this memo.
  2727.  
  2728. Author's Address
  2729.  
  2730.    James Rice
  2731.    Stanford University
  2732.    Knowledge Systems Laboratory
  2733.    701 Welch Road
  2734.    Building C
  2735.    Palo Alto, CA 94304
  2736.  
  2737.    Phone: (415) 723-8405
  2738.    EMail: RICE@SUMEX-AIM.STANFORD.EDU
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746. Rice                                                           [Page 49]
  2747.